---
url: /guide/compatibility.md
---

# Compatibility

This article explains how to ensure version compatibility between [Bundle] and [Lynx Engine], and how to handle challenges that come with Lynx Engine version evolution.

## Build from Source

A simple way to ensure compatibility is to **always build the Bundle with the Host application from source**.

- Bundle can fully utilize all features of the current Lynx Engine version
- Compatibility can be fully verified during development, what you see is what you get

## Multi-version Compatibility

However, in a complex project, the relationship between Bundle and Lynx Engine is not one-to-one:

- A Bundle might run in applications with different Lynx Engine versions

- An application can run multiple Bundles maintained by different teams

In this case, you need to set the [`engineVersion`] to ensure compatibility.

:::info Engine Version
When the Bundle's [`engineVersion`] is greater than the Lynx Engine version, it will not be able to run.
:::

For example: a Bundle with [`engineVersion`] 3.3 can run on Lynx Engine 3.3 and later versions, but cannot run on 3.2.

<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



---
url: /guide/custom-native-component.md
---

# Custom Element

If the built-in elements do not meet your requirements, you can extend Lynx's capabilities by creating custom native elements. This section will guide you through creating and registering custom elements on Android, iOS and HarmonyOS platforms.

:::info Prerequisites

✅ Completed [Quick Start](/guide/start/quick-start.md)

✅ Completed [Lynx Integration](/guide/start/integrate-with-existing-apps.md)

✅ Familiar with [element Basics](/guide/ui/elements-components.md)

:::

## Building your Native Code

<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` | Web: `dist/main.web.bundle`

```tsx {33-39}
import { useState } from "@lynx-js/react";
import * as Lynx from "@lynx-js/types";

import "./App.css";

export function App() {
  const [inputValue, setInputValue] = useState("");

  const handleInput = (e: Lynx.BaseEvent<"input", { value: string }>) => {
    const currentValue = e.detail.value.trim();
    setInputValue(currentValue);
  };

  const requestFocus = () => {
    lynx
      .createSelectorQuery()
      .select("#input-id")
      .invoke({
        method: "focus",
        params: {},
        success: function(res) {
          console.log("lynx", "request focus success");
        },
        fail: function(res) {
          console.log("lynx", "request focus fail");
        },
      })
      .exec();
  };

  return (
    <view className="input-card-url">
      <text className="bold-text">Card URL</text>
      <explorer-input
        id="input-id"
        className="input-box"
        bindinput={handleInput}
        value={inputValue}
        placeholder="Enter Card URL"
      />
      <view className="connect-button" bindtap={requestFocus}>
        <text className="button-text">Go</text>
      </view>
    </view>
  );
}

```





---
url: /guide/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!



---
url: /guide/devtool/handle-errors.md
---

# Handle Errors in Lynx

## Recognize Errors in Tools

When you are developing Lynx apps, you may encounter various types of errors that are designed to notify you the unexpected situations that have just happened.

For example, if the bundle file is broken, you'll see:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/error_invalid_bundle.png" alt="Bundle is broken" width="20%" />

Also, sometimes when your JavaScript code contains an TypeError:

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

Sometimes, a [native module](/guide/spec.md#nativemodules) is called with a wrong number of arguments:

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

With DevTool or LogBox, you shall easily recognize them.

## LogBox

You've already seen it above - the in-app tool that displays errors.

<div style={{ display: 'flex', justifyContent: 'flex-start', gap: '10px' }}>
  <img
    src={
    'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/logbox_message.jpeg'
  }
    alt="LogBox notification"
    style={{ width: '40%', height: '40%', margin: 'auto 0' }}
  />

  <img
    src={
    'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/logbox_box.png'
  }
    alt="LogBox red"
    width="30%"
  />
</div>

It's convenient for a quick overview and lets you know what's happening.
However, for development purposes, we recommend using DevTool Desktop Application with more features and a better interactive experience.

## Handle Errors in Code

Now let's try to do something with the errors.

You may want to have an overall understanding of the [errors](/api/errors/lynx-error.md) first if you want to handle them in your code.

And then, here is an example of handling error [301](/api/errors/error-code.md#eb_resource_image-301) in code:

```tsx
const ImageErrorExample = () => {
  const [isImageError, setImageError] = useState(false);
  const handleImageError = (event: ErrorEvent) => {
    setImageError(true);
    console.log('Image loaded error:', JSON.stringify(event));
  };
  if (isImageError) {
    return <view />;
  }
  return (
    <view>
      <image
        className="my-image"
        src={'error url'}
        binderror={handleImageError}
      />
    </view>
  );
};
```

In order for developers to quickly categorize an error and figure out how to deal with it, we have summed up all of them and made a [list](/api/errors/error-code.md), including the error code, description, level, fix suggestion, etc.

Just help yourself!

## Compatibility


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

**Platform Support**

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

**Description:** Shows logbox details




---
url: /guide/devtool/panels.md
---

# Panels

## Choose Page and Debugging Options

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

There may be multiple Lynx page instances at the same time in a page.
For debugging between different page instances,
you need to select the current page instance to be debugged.

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

At the bottom of the debugging options page, you can select the page to be debugged.
Move the mouse over the page path, and the page thumbnail will be displayed on the right.

In the debugging options menu, there are App Info for displaying application and Lynx information,
and Settings for setting debugging options.

## Debugging Panels

Dive into the debugging functions.

### Elements

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-elements.png)

The **Elements** panel allows you to inspect and modify elements.

- [View Element Nodes](/guide/devtool/panels/elements-panel.md#view-dom-nodes)
- [Edit the Element](/guide/devtool/panels/elements-panel.md#edit-the-dom)
- [View and Change CSS](/guide/devtool/panels/elements-panel.md#view-and-change-css)
- [Find Invalid, Overridden, and Other CSS](/guide/devtool/panels/elements-panel.md#find-invalid-overridden-and-other-css)

### Console

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-console.png)

Use the **Console** panel to view logged messages and run JavaScript.

- [View Logged messages](/guide/devtool/panels/console-panel.md#view-logged-messages)
- [Run JavaScript](/guide/devtool/panels/console-panel.md#run-javascript)
- [Clear the Console](/guide/devtool/panels/console-panel.md#clear-the-console)

### Sources

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-sources.png)

Use the **Sources** panel to debug JavaScript.

- [File Navigation](/guide/devtool/panels/sources-panel.md#file-navigation)
- [Pause Code with Breakpoints](/guide/devtool/panels/sources-panel.md#pause-code-with-breakpoints)
- [Debug JavaScript](/guide/devtool/panels/sources-panel.md#debug-javascript)
- [Debug Original Code with Source Maps](/guide/devtool/panels/sources-panel.md#debug-original-code-with-source-maps)
- [Debug the Main Thread](/guide/devtool/panels/sources-panel.md#debug-the-main-thread)

### Layers

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-layers.png)

Helps you understand the composition of Lynx pages and how the framework presents content, analyzing its 3D layers to discover rendering issues.

- [View page Layers](/guide/devtool/panels/layers-panel.md#view-page-layers)
- [Inspect page Layers](/guide/devtool/panels/layers-panel.md#inspect-page-layers)



---
url: /guide/devtool/panels/console-panel.md
---

<style jsx>
  {`
    .inline-content {
      display: flex;
      align-items: center;
      flex-wrap: wrap;
    }
    .inline-content img {
      margin: 0 5px;
      height: 2rem;
    }
    .margin {
      margin-top: 1rem;
      margin-bottom: 1rem;
    }
    .margin2 {
      margin-top: 0.5rem;
    }
    `}
</style>

# Console Panel

## Overview

Use the **Console** panel to [view logged messages](#view-logged-messages) and [run JavaScript](#run-javascript). Before you start debugging, please take some time to familiarize yourself with the [Lynx JavaScript Runtime](/guide/scripting-runtime/index.md#javascript-runtime).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/console-panel.png" alt="Console panel" style={{ width: 800 }} />

### Open the Console Panel

The Console can be opened as a panel or as a tab in the Drawer.

#### Open in the Drawer

If you want to view the Console panel while using other panels, you can open the Console in the Drawer.

Please refer to [Open the Console in the Drawer | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#drawer).

### Console Settings

<div class="inline-content margin">
  <span>
    Click 

    **Console Settings**

     
  </span>

  <img
    src={
    'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/console-settings.png'
  }
    alt="Console settings"
  />

  <span>
     in the top-right corner of the 

    **Console**

     panel.
  </span>
</div>

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/console-settings-pane.png" alt="Console settings pane" style={{ width: 800 }} />

The following links explain each setting:

- [Selected context only](#filter-messages-from-different-contexts)
- [Group similar messages in console](#disable-message-grouping)
- [Eager evaluation](#disable-eager-evaluation)
- [Autocomplete from history](#disable-autocomplete-from-history)

### Console Sidebar

Please refer to [Open the Console Sidebar | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#sidebar).

## View Logged messages

The types of logs currently can be viewed include:

1. **JavaScript logs**. Including the main thread and the background thread.

   - By default, logs from the background thread are displayed in full format, while logs from the main thread are serialized as strings with the `[main-thread.js]` prefix.
   - When [Main Thread Debugging](/guide/devtool/panels/sources-panel.md#debug-the-main-thread) is enabled, logs from the main thread will also be displayed in full format.

2. **Some client logs**.

   Currently, client runtime errors and some other client logs are serialized as strings and displayed in the Console panel.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/log-type.png" alt="Log type" style={{ width: 800 }} />

### Log Sources

For JavaScript logs, the `App.tsx:11` on the right side of the log represents where it logged. Clicking it will open the [Sources](/guide/devtool/panels/sources-panel.md) panel and highlight the line of code that caused the message to get logged to the Console.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/call-stack.png" alt="Call stack" style={{ width: 800 }} />

### Disable Message Grouping

DevTool enables **Group similar messages in console** by default, which aggregates similar messages logged consecutively.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/group-similar-log.png" alt="Group similar log" style={{ width: 800 }} />

Open [Console Settings](#console-settings) and disable this option to expand the logs that were originally grouped.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/disable-group-similar-log.png" alt="Disable group similar log" style={{ width: 800 }} />

### View Stack Traces

<div class="inline-content margin">
  <span>
    For JavaScript errors and warnings, click 

    **Expand**

     
  </span>

  <img
    src={
    'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/stack-trace-expand.png'
  }
    alt="Stack trace expand"
  />

  <span>
     to view the stack trace.
  </span>
</div>

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/stack-trace.png" alt="Stack trace" style={{ width: 800 }} />

### Filter messages

#### Filter by Log Level

Please refer to [Filter by log level | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#level).

:::tip
When the sidebar is open, you cannot click the log level drop-down.
:::

#### Filter by Text

Please refer to [Filter by text | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/log#text).

#### Filter by Regular Expressions

Please refer to [Filter by regular expression | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/log#regex).

#### Filter by URL

Please refer to [Filter messages by URL | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#url).

#### Filter Messages from Different [Contexts](/guide/spec.md#scripting-runtime-enviroment①)

By default, all logs are displayed within the context of the background thread. When [Main thread debugging](/guide/devtool/panels/sources-panel.md#debug-the-main-thread) is enabled, an additional context of the main thread will be added.

As shown in the figure, `Background:-1` represents the background thread, and `Main` represents the main thread.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/filter-by-context.png" alt="Filter by context" style={{ width: 800 }} />

When you [run JavaScript in the Console](#run-javascript), it will execute only within the currently selected context.

Open [Console Settings](#console-settings) and enable **Selected context only** checkbox to display logs only from the currently selected context.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/selected-context-only.png" alt="Filter by context" style={{ width: 800 }} />

### Search for Text

Please refer to [Search for text in logs | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#search).

## Run JavaScript

The Console is a **REPL**, which stands for "Read, Evaluate, Print, and Loop." It reads the JavaScript you enter, evaluates your code, outputs the result of the expression, and then loops back to the first step.

You can enter expressions related to the current page in the Console, such as `this`.

You can also enter expressions unrelated to the current page, such as `1+2`.

Press Enter to get the result, and the Console will output the result of the expression below the code.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/run-script.png" alt="Run script" style={{ width: 800 }} />

### String Copy Options

Please refer to [String copy options | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#string-copy-options).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/copy-string.png" alt="Copy string" style={{width:800}} />

For example, in this case, the results of copying are as follows:

```javascript
{"a":123,"b":"string"}
'{"a":123,"b":"string"}'
"{\"a\":123,\"b\":\"string\"}"
```

### Re-run Expressions from History

Please refer to [Re-run expressions from history | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#history).

### Watch Expression Values in Real-Time

Please refer to [Watch JavaScript values in real time with Live Expressions | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/live-expressions).

### Disable Eager Evaluation

Please refer to [Disable Eager Evaluation | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#eagereval).

### Disable Autocomplete from History

Please refer to [Disable autocomplete from history | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#autocomplete).

## Clear the Console

You can use any of the following workflows to clear the Console:

- <div class="inline-content margin2">
    <span>
      Click 

      **Clear Console**
    </span>

    <img
      src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/clear-console-button.png'
    }
      alt="Clear console button"
    />

    <span>
      .
    </span>
  </div>
- Right-click a log and select **Clear Console**.
- When the Console is in focus, press Control+L or Command+K.
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/clear-console.png" alt="Clear console" style={{ width: 800 }} />

## Compatibility


**Error:** No compatibility data found for `devtool.panels.console`


---
url: /guide/devtool/panels/elements-panel.md
---

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

# Elements Panel

The **Elements** panel allows you to inspect and modify element and element tree.

## Overview

The **Elements** panel provides a powerful interface for inspecting and manipulating the element and the element tree. You can select specific element using the element tree and use other tools to make modifications.

The **Elements** panel also includes tabs for the following related tools:

- **Styles**:
  - [View and debug](#viewing-and-changing-css) CSS rules applied to an element from all stylesheets.
  - Find any [invalid, overridden, or otherwise not working CSS](#invalid-and-declarations-with-invalid-values).
  - Modify elements by [adding declarations](#adding-css-declarations-to-an-element), and [interacting with the Box model](#interacting-with-elements-in-the-lynx-page-preview-window-via-the-box-model).
- **Computed**: Lists the resolved properties applied to an element.

### Open the Elements Panel

By default, when you open the Lynx DevTool desktop application and connect to a device to debug Lynx pages, the **Elements** panel will open.

To manually open or switch back to the **Elements** panel from another panel, click on the **Elements** tab in the main panel of the DevTool window.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-drawer.png" width="400px" style={{ margin: '20px' }} />

### Preview Panel

The left side of the **Elements** panel is the Lynx Page Preview Window, showing the Lynx page content for mobile devices in real-time.

#### Introduction to the Preview Panel

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/screencast.png" class="full_image" />

As shown in the above figure:

1. Click the reload icon in the upper left corner to refresh the Lynx page.
2. SD/HD toggle switch, adjust current debugging screen mirroring clarity.
3. Switch current screen mirroring mode, there are two modes: LynxView and FullScreen.
   - When there are multiple Lynx pages on the current screen, it is recommended to use the LynxView screen mirroring mode, so that you can focus on the currently selected debugging page.
   - If the Lynx page has an overlay component (this component is in a separate window and may be outside the LynxView display area), it is recommended to use the FullScreen mode, and the entire screen content of the mobile phone will be captured at this time.
4. The border that separates the Elements panel and the preview window can be dragged to adjust their size.
5. Displays the JS engine used by the current page.

#### Open/Close the Preview Panel

Click on this icon to open/close the preview window.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/screencast-switch.png" class="full_image" />

After closing, it will be displayed as follows:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/screencast-close.png" class="full_image" />

At this time, if an element that can generate UI is selected in the Elements panel (not all nodes on the element tree will eventually generate platform UI), the Lynx page on the mobile phone will highlight the corresponding element.

## View Element Nodes

### Inspect Nodes

1. Click on the **Inspect** icon in the upper left corner of the developer tools.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-inspect.png" width="400px" style={{ margin: '20px' }} />

2. Click on the logo in the upper left corner of the preview window.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-click1.png" alt="Click Inspect" class="full_image" />

3. Now, the corresponding `<image></image>` node is highlighted in the element tree.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-click2.png" alt="Click Inspect" class="full_image" />

### Navigate the Element Tree with a keyboard

After selecting a node in the element tree, you can use the keyboard to browse the element tree.

1. After clicking on the **Inspect** icon in the upper left corner of the developer tools, click on the input box in the middle of the Lynx page preview window.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-key1.png" width="600" class="full_image" />

Now, the `<input>` node is selected in the element tree.

2. Press the Up arrow key twice. `<view class="input-card-url__light">` has been selected.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-key2.png" class="full_image" />

3. Press the left arrow key. All child nodes of `<view class="input-card-url__light">` will be collapsed.

4. Press the left arrow key again, and the parent `<view class="input-card-url__light">` of `<view class="page__light">` will be selected.

5. Press the Down arrow key twice to reselect the `<view class="input-card-url__light">` node that you just collapsed. The displayed content should be as follows: `<view class="input-card-url__light">...</view>`.

6. Press the right arrow key. At this time, the `<view class="input-card-url__light">` node will be expanded.

## Edit the Element

You can dynamically modify the element and see how these changes affect the Lynx page.

### Edit Content

To modify the content of a node, double-click on the corresponding content in the element tree.

As shown above:

1. After clicking on the **Inspect** icon, click on the text **Lynx Explorer** in the Lynx page preview window. Now the `<text class="home-title__light">...</text>` node is selected in the element tree.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/text-modify1.png" class="full_image" />

2. Press the right arrow key on the keyboard to expand the `<text class="home-title__light">...</text>` node.

3. Press the down arrow key on the keyboard, and the `<raw-text text="Lynx Explorer"><raw-text>` node is selected in the element tree.

4. Double-click on the **Lynx Explorer** on `<raw-text>`.

5. Modify the content to **Hello world**.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/text-modify2.png" class="full_image" />

6. Press the Enter key, and you can see that the text change has taken effect both in the element tree and on the left preview window.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/text-modify3.png" class="full_image" />

### Edit Attributes

To modify attributes, double-click on the attribute name or value. Follow the instructions below to learn how to modify the style attribute of a node.

1. Select the `<view clip-radius="true" flatten="false" style="height:100px">` node in the element tree that you want to modify.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/style-modify1.png" class="full_image" />

2. Double-click on the part that displays `style="height:100px;"`, and the text will be highlighted.

3. Modify the **style** content to `style="width:70%;height:100px;"`.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/style-modify2.png" class="full_image" />

4. Press the Enter key, and you can see that the width change of the view has taken effect both in the element tree and on the left preview window.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/style-modify3.png" class="full_image" />

## View and Change CSS

### View CSS for an Element

1. Click on the **Inspect** icon, and click on the text **Lynx Explorer** in the preview window.

2. The `<text class="home-title__light">...</text>` node is selected in the element tree.

3. At this time, you can see that the **Styles** tab shows all the styles applied to the currently selected node.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-style-check.png" class="full_image" />

4. Switch to the **Computed** tab in the upper tab bar, and you can see the box model of the selected node, as well as all the resolved styles finally applied to the node.

### Add CSS Declarations to an Element

If you want to change or add CSS declarations to an element, use the **Styles** tab.

1. Selected `<view clip-radius="true"...>...</text>` in the element tree.

2. On the right side of the **Styles** tab, click on the top `element.style`.

3. After clicking, enter the property name `border` and press the Enter key. A second input box will pop up, enter `black 20px`.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-style-modify1.png" class="full_image" />

4. Press the Enter key again. At this time, whether it is the UI effect on the preview window or the element tree, the style change has taken effect.
   {' '}

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-style-modify2.png" class="full_image" />

### Interact with Elements in the Lynx Page preview window via the Box Model

1. Click on the **Inspect** icon, and hover over the Go button in the preview window.

2. At this time, you can see that all the box models are highlighted in the left preview window, from the inside to the outside are **content-box**/ **padding-box** / **border-box** / **margin-box**.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/box-model.png" class="full_image" />

3. Click Go button, then corresponding `<view ...>...</view>` node is selected in the element tree.

4. Click on the box model in the **Styles** tab on the right side, and click one by one from the inside to the outside, you can see that the left preview window is highlighted one by one in turn. Using content-box as an example, as shown in the image below:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/box-model2.png" class="full_image" />

## Find Invalid, Overridden, and Other CSS

### Check the CSS You Wrote

Suppose you added some CSS to an element and want to make sure the new styles are applied correctly. When you refresh the page, the element looks the same as before. Something went wrong.

The first thing to do is to inspect the element and make sure the new CSS is actually applied to the element.

Sometimes, you will see the new CSS in the **Elements** > **Styles** pane, but the new CSS appears as faded text, cannot be modified, is crossed out, or a warning or hint icon is displayed next to it.

### Understand CSS in the **Styles** Pane

The Styles pane can identify various CSS issues and highlight them in different ways.

#### Invalid and Declarations with Invalid Values

The **Styles** pane will cross out the following and display a warning icon next to the following:

- When the CSS property is invalid or unknown, the entire CSS declaration (property and value).
- When the CSS property is valid but the value is invalid, the entire CSS declaration (property and value).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-check1.png" class="full_image" />

#### Overridden

The **Styles** pane will cross out properties that are overridden by other properties according to the cascade order.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-check2.png" class="full_image" />

In this example, the `color:red;` style property on the element will override the `color:linear-gradient(120deg,#0095ff 30%,#42d392 100%);` on the `.banner.title` class.

#### Inherited and Non-Inherited

The **Styles** pane will list properties in the `Inherited from <element-name>` section based on the default inheritance relationship of the property:

- Inherited content will be shown in regular text by default.
- Non-inherited content will be shown in light text by default.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-check3.png" class="full_image" />

## Compatibility


### View and Edit

**Error:** No compatibility data found for `devtool.panels.elements.view-and-edit`
### Preview

**Error:** No compatibility data found for `devtool.panels.elements.preview`


---
url: /guide/devtool/panels/layers-panel.md
---

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

# Layers Panel

The **Layers** panel helps you understand the composition of Lynx pages and how the framework presents content, analyzing its 3D layers to discover rendering issues.

## Overview

Use the **Layers** panel to perform the following operations:

- View page layers
- Inspect page layers

### Open the Layers Panel

To open the Layers panel, follow these steps:

1. Press **Command+Shift+P** to open the command menu.
2. Start typing **Layers**, select **Show Layers**, and then press **Enter**.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/open-layers.png" width="400" style={{ margin: '20px' }} />

Or, select the More options in the upper right corner -> **More tools** -> **Layers**.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/open-layers2.png" width="400" style={{ margin: '20px' }} />

## View page Layers

The leftmost part of the **Layers** panel lists all the rendered layers of the Lynx page in an expandable tree. This tree structure is updated as the mobile **Lynx** page is updated. Layers are identified by their **CSS** selector or a number (followed by the layer size in pixels).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/view-layers.png" class="full_image" />

Hover the mouse over a layer to highlight it on the Lynx page preview window. A tooltip will be displayed on the page preview, which contains the following information:

- The selector of the layer
- The size of the layer (in pixels)

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/view-layers-screen.png" class="full_image" />

## Inspect page Layers

Click on a layer to view more information in the **Details** pane.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/check-layer-details.png" class="full_image" />

Depending on the layer, the following information will be displayed:

- Size
- Compositing reason
- Memory estimate
- Number of draws

The following figure shows the stacking and arrangement of the layers of this **Lynx** page.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/layer-3d-view.png" class="full_image" />

To move the chart, do the following:

- Use **WASD** to move the chart. Press W to pan up, A to pan left, S to pan down, and D to pan right.
- Click the **Pan Mode** icon to move along the X and Y axes.
- Click the **Rotate Mode** icon to rotate along the Z axis.
- Click **Reset Transform** to reset the chart to its original position.
- Scroll the mouse wheel up to zoom in.
- Scroll the mouse wheel down to zoom out.

To view the element corresponding to the layer in the **Elements** panel, right-click on the corresponding layer in the chart or layer tree, and then click **Reveal in Elements panel**.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/layer-element.png" class="full_image" />

## Compatibility


**Compatibility Table**
**Query:** `devtool.panels.layers`

**Platform Support**

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

**Description:** View page layers




---
url: /guide/devtool/panels/preact-devtools-panel.md
---

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

# Preact Devtools Panel

The **Preact Devtools** panel helps you inspect the hierarchy of ReactLynx components, displaying information such as component props, state, and file paths. The Preact Devtools panel is based on the [Preact Devtools](https://preactjs.github.io/preact-devtools/) web browser extension and offers the same user experience.

## Overview

With the **Preact Devtools** panel, you can:

- View the component hierarchy of ReactLynx
- Modify props or state and see real-time updates
- Use ClickToComponent to navigate to component source code
- Use the Profiler to analyze application performance

### Open the Preact Devtools Panel

In the DevTool window, click the Preact Devtools tab in the main panel to open it.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/open-preact-devtools.jpg" width="600" style={{ margin: '20px' }} />

Note: Before using the **Preact Devtools** panel, you need to import [`@lynx-js/preact-devtools`](https://www.npmjs.com/package/@lynx-js/preact-devtools) at the **first line** of your ReactLynx application's entry file:

```js
import '@lynx-js/preact-devtools';
```

## View Component Hierarchy

The left side of the **Preact Devtools** panel shows the complete hierarchy of the ReactLynx application, while the right side displays detailed information about the selected component, including its props, state, and file path.

Hover over a component to highlight its corresponding box model in the preview window on the left.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/component-hierarchy.jpg" class="full_image" />

## View and Modify Props or State

On the right side of the **Preact Devtools** panel, you can directly modify the props or state of components, and the ReactLynx application's UI will update in real-time.

As shown below, we changed the state used for counting in the `Counter` component from `1` to `2`, and the counter UI on the page also changed from `1` to `2`.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/state-modify.jpg" class="full_image" />

## ClickToComponent for Source Navigation

We integrated the [ClickToComponent](https://github.com/ericclemmons/click-to-component) into the **Preact Devtools** panel. By clicking the file path under **source location**, VSCode will automatically open the file containing the component and navigate to the corresponding line and column.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ClickToComponent.jpeg" class="full_image" />

## Profiler

The Profiler panel supports performance analysis of ReactLynx component rendering time on background thread. Click the button in the top-left corner to start recording, let the application run for a while, and then click the button again to stop. You will then get information about all Preact commits during that time, as well as the rendering time of each component within the same commit.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/preact-devtools-profiler.jpg" class="full_image" />



---
url: /guide/devtool/panels/sources-panel.md
---

<style jsx>
  {`
    .inline-content {
      display: flex;
      align-items: center;
      flex-wrap: wrap;
    }
    .inline-content img {
      margin: 0 5px;
      height: 2rem;
    }
    .margin {
      margin-top: 1rem;
      margin-bottom: 1rem;
    }
    .margin2 {
      margin-top: 0.5rem;
    }
    `}
</style>

# Sources Panel

Use the **Sources** panel to debug JavaScript. Before you start debugging, please take some time to familiarize yourself with the [Lynx JavaScript Runtime](/guide/scripting-runtime/index.md#javascript-runtime).

After DevTool is enabled, the background thread uses the PrimJS engine for debugging by default. On Android, you can also switch to the V8 engine for a more comprehensive debugging experience.

To switch to the V8 engine, open the [DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch), toggle the "**V8 Engine**" switch to "**On**" and restart the application. You can check the current engine type in the lower-left corner of the [Preview Window](/guide/devtool/panels/elements-panel.md#introduction-to-the-preview-panel).

## Overview

The **Sources** panel has three sections:

1. **File Navigation Pane**. All JavaScript files of the page are listed here.
2. **Code Editor Pane**. After selecting a file in the **File Navigation Pane**, the contents of the file are displayed here.
3. **Debugger Pane**. Various tools for inspecting the page's JavaScript.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sources-panel.png" alt="Sources panel" style={{ height: 400 }} />

## File Navigation

### Open File

You can use the **File Navigation Pane** or the **Open file** feature to open the file of interest.

<div class="inline-content margin">
  <span>
    Click 

    **More Options**

     
  </span>

  <img
    src={
    'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/more-options.png'
  }
    alt="More options"
  />

  <span>
    and select 

    **Open file**

    . A dialog will display.
  </span>
</div>

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/open-file.png" alt="Open file" style={{ height: 200 }} />

You can enter the file URL here or select a file from the drop-down list.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/open-file-dialog.png" alt="Open file dialog" style={{ height: 300 }} />

The bottom status bar of the **Code Editor Pane** will display the line and column number of the current mouse position.

<div class="inline-content margin">
  <span>
    Click 

    **Show navigator**

     
  </span>

  <img
    src={
    'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/show-navigator.png'
  }
    alt="Watch Add"
  />

  <span>
    button to collapse/expand the 

    **File Navigation Pane**

    .
  </span>
</div>

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/file-editor.png" alt="File editor" style={{ height: 400 }} />

### Close File

You can close a file in the following ways:

- Hover the mouse over the file name tab at the top of the **Code Editor Pane** and click the **close** button.
  <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/close-file-button.png" alt="Close file button" style={{ width: 400 }} />
- Right-click the file name tab at the top of the **Code Editor Pane**:
  - Close: Close the current file.
  - Close others: Close other files.
  - Close all: Close all files.
    <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/close-file.png" alt="Close file" style={{ height: 300 }} />

### Locate File

To locate the file currently displayed in the **Code Editor Pane**:

1. Right-click anywhere in the **Code Editor Pane** or right-click the file name tab at the top of the **Code Editor Pane**.
2. Select **Reveal in sidebar**.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/reveal-in-sidebar.png" alt="Reveal in sidebar" style={{ height: 400 }} />

### Search Code

To search a code segment:

1. <div class="inline-content margin">
     <span>
       Click 

       **Customize And Control DevTools**
     </span>

     <img
       src={
       'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/more-options.png'
     }
       alt="More options"
     />

     <span>
        \> 

       **Search**

        to open the 

       **Search**

        panel.
     </span>
   </div>
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/search.png" alt="Search" style={{ height: 300 }} />
2. Enter text and press Enter to search.
3. Click search results to jump to the corresponding file and the code will be highlighted.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/search-panel.png" alt="Search panel" style={{ height: 400 }} />

You can also:

- <div class="inline-content margin2">
    <span>
      Click 

      **Match Case**

       
    </span>

    <img
      src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/match-case.png'
    }
      alt="Step out"
    />

    <span>
      to make the query case-sensitive.
    </span>
  </div>
- <div class="inline-content margin2">
    <span>
      Click 

      **Use Regular Expression**

       
    </span>

    <img
      src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/use-regular.png'
    }
      alt="Step out"
    />

    <span>
      to search using a RegEx.
    </span>
  </div>
- <div class="inline-content margin2">
    <span>
      Click 

      **Refresh**

       
    </span>

    <img
      src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/refresh.png'
    }
      alt="Step out"
    />

    <span>
      to search again.
    </span>
  </div>
- <div class="inline-content margin2">
    <span>
      Click 

      **Clear**

       
    </span>

    <img
      src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/clear.png'
    }
      alt="Step out"
    />

    <span>
      to clear the input contents.
    </span>
  </div>

## Pause Code with Breakpoints

By adding breakpoints, you can pause the code execution and inspect all relevant values at that moment.

Currently supported breakpoint types are as follows:

|                                Type                               | Description                                                                   |
| :---------------------------------------------------------------: | ----------------------------------------------------------------------------- |
|             [Line-of-code](#line-of-code-breakpoints)             | Pause on an exact region of code.                                             |
| [Conditional line-of-code](#conditional-line-of-code-breakpoints) | Pause on an exact region of code, but only when some other condition is true. |
|             [Logpoint](#log-line-of-code-breakpoints)             | Log a message to the Console without pausing the execution.                   |
|               [First line](#first-line-breakpoints)               | Pause on the first line of every executed JavaScript file.                    |
|                [Exception](#exception-breakpoints)                | Pause on the line of code that is throwing a caught or uncaught exception.    |

### Line-of-Code Breakpoints

Please refer to [Line-of-code breakpoints | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#loc).

#### Line-of-Code Breakpoints in Code

Please refer to [Line-of-code breakpoints in your code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#debugger).

#### Conditional Line-of-Code Breakpoints

Please refer to [Conditional line-of-code breakpoints | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#conditional-loc).

#### Log Line-of-Code breakpoints

Please refer to [Log line-of-code breakpoints | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#log-loc).

#### Manage Line-of-Code Breakpoints

Right-click the breakpoint icon or use the **Breakpoints** pane to manage line-of-code breakpoints.

- Right-click the breakpoint icon and select **Edit breakpoint** to edit it. You can also change its type from the drop-down list in the inline editor.
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/edit-bp.png" alt="Edit breakpoint" style={{ height: 200 }} />

- Click the breakpoint icon again to delete the breakpoint.

- In the **Breakpoints** pane, click the checkbox next to the breakpoint entry to enable or disable the breakpoint. When disabled, the marker next to the line number will become transparent.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/disable-bp.png" alt="Disable breakpoint" style={{ height: 300 }} />

- Right-click the breakpoint icon to see the options menu:
  - Remove breakpoint.
  - Edit breakpoint.
  - Disable/Enable breakpoint.
    <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/bp-action.png" alt="Breakpoint action" style={{ height: 300 }} />

- Right-click the breakpoint entry in the **Breakpoints** pane to see the options menu:
  - Remove breakpoint.
  - Reveal location.
  - Deactivate/Activate breakpoints.
    <div class="inline-content margin2">
      <span>
        You can also use 

        **Deactivate breakpoints**

         
      </span>

      <img
        src={
        'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/deactivate-bp.png'
      }
        alt="Step out"
      />

      <span>
        button to deactivate breakpoints.
      </span>
    </div>
    When breakpoints are deactivated, DevTool will ignore all line-of-code
    breakpoints, and they will not be triggered. All breakpoints will remain in
    the same state after being reactivated.
  - Disable/Enable all breakpoints.
  - Disable/Enable breakpoints in file.
  - Remove all breakpoints.
  - Remove other breakpoints.
    <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/bp-pane-action.png" alt="Breakpoint pane action" style={{ height: 300 }} />

#### Skip Breakpoints with 'Never Pause Here' <Badge>Background V8 Only</Badge>

Please refer to [Skip breakpoints with 'Never pause here' | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#never-pause-here).

### First-Line Breakpoints <Badge>Background Only</Badge>

Use first-line breakpoints to pause at the entry of every executed JavaScript file.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/first-line-bp-example.png" alt="First line breakpoint example" style={{ height: 400 }} />

Hover your mouse over the position shown in the image, then enable **First-Line Breakpoints**. This is a non-persistent global switch that takes effect for all pages during a single APP run. The switch state will be reset after closing and restarting the APP.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/first-line-bp.png" alt="First line breakpoint" style={{ height: 400 }} />

You can debug first-line breakpoints in two ways:

1. Turn on the switch, then open the page you want to debug.
2. Open the page you want to debug, turn on the switch, and then [reload](/guide/devtool/panels/elements-panel.md#introduction-to-the-preview-panel) the page.

### Exception Breakpoints

Use exception breakpoints when you want to pause on the line of code that's throwing a caught or uncaught exception.

1. In the **Breakpoints** pane, click the **Pause on exceptions** button, which turns blue when enabled.
2. By default, it only pause on uncaught exceptions. If you also want to pause on caught exceptions, check the **Pause On Caught Exceptions** checkbox.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/pause-on-exceptions.png" alt="Pause on exceptions" style={{ height: 300 }} />

:::warning

Currently, the PrimJS engine does not distinguish between caught and uncaught
exceptions, and all exceptions will cause a pause. In contrast, the V8 engine
distinguishes between caught and uncaught exceptions.

:::

## Debug JavaScript

By default, you can only debug the background thread. If you need to debug the main thread, please refer to the section [Debug the Main Thread](#debug-the-main-thread).

### Step Through Code

Once your code is paused, step through it, one expression at a time, investigating control flow and property values along the way.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/pause.png" alt="Pause" style={{ height: 150 }} />

#### Step Over

Please refer to [Step over line of code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#step-over).

#### Step Into

Please refer to [Step into line of code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#step-into).

#### Step Out

Please refer to [Step out of line of code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#step-out).

#### Run All Code Up to a Certain Line <Badge>Background V8 Only</Badge>

Please refer to [Run all code up to a certain line | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#continue-to-here).

#### Resume

Please refer to [Resume script execution | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#resume).

##### Terminate Execution <Badge>Background V8 Only</Badge>

To stop your script's execution after a pause, click and hold the **Resume** button and then select **Terminate script execution** button.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/terminate-execution-example.png" alt="Terminate script execution example" style={{ height: 150 }} />

For example, in this case, select **Terminate script execution**, DevTool will
stop executing the script, the rest of the code in `add` will not be executed,
and you will see that the value of `count` will not change.

### View and Edit Properties

Please refer to [View and edit local, closure, and global properties | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#scope).

### View the Current Call Stack

When paused on a line of code, you can use the **Call Stack** pane to view the call stack that got you to this point.

Select an entry in the pane to jump to the line of code where the function was called. A blue arrow icon represents the currently highlighted code.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/call-stack.png" alt="Call stack" style={{ height: 300 }} />

#### Copy Stack Trace

Right-click anywhere in the **Call Stack** pane and select **Copy stack trace** to copy the current call stack to the clipboard.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/copy-stack-trace.png" alt="Copy stack trace" style={{ height: 300 }} />

For example, in this case, the copied stack trace is as follows:

```
add (App.tsx:11)
publishEvent (tt.js:148)
```

### Ignore Scripts <Badge>Background V8 Only</Badge>

Ignore certain scripts during debugging to skip them. When ignored, scripts will be hidden in the **Call stack** pane, and you will never step into functions from ignored scripts while stepping through code.

#### Ignore a Script from the Editor Pane

Please refer to [Ignore a script from the Editor pane | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#editor-ignore-list).

#### Ignore a Script from the Call Stack Pane

Please refer to [Ignore a script from the Call Stack pane | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#call-stack-ignore-list).

#### Show ignore-listed frames

If you need to view the complete call stack, click **Show ignore-listed frames** in the **Call Stack** pane. The ignored frames will be expanded but displayed in gray.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/show-ignore1.png" alt="Show ignore1" style={{ width: 500 }} />

<br />

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/show-ignore2.png" alt="Show ignore2" style={{ width: 500 }} />

#### Unignore Scripts

To unignore scripts, follow the same steps as above and select **Remove from ignore list**.

You can also unignore scripts through the prompt at the top of the **Code Editor Pane**.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/remove-ignore.png" alt="Remove ignore" style={{ width: 500 }} />

### Watch the Values of Custom JavaScript Expressions

Please refer to [Watch the values of custom JavaScript expressions | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#watch).

### Inspect and Edit Scripts

In the **Code Editor Pane**, you can browse and edit code.

#### Make Minified Files Readable

Click the `{}` button in the bottom status bar of the editor, and the **Sources** panel will present the minified file in a more readable format to improve readability.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/format-before.png" alt="Format before" style={{ width: 500 }} />

<br />

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/format-after.png" alt="Format after" style={{ width: 500 }} />

#### Edit Scripts <Badge>Background V8 Only</Badge>

Please refer to [Edit a script | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#edit).

:::warning
You can only modify compiled JavaScript files. The original files reversed through SourceMap cannot be modified, and changes will not be saved after reloading the page.
:::

#### Search and Replace Text in Scripts

Please refer to [Search and replace text in a script | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#search).

After replacing, you need to manually save the script, as referenced in [Edit Scripts](#edit-scripts).

## Debug Original Code with Source Maps <Badge>Background Only</Badge>

After [configuring SourceMap](/api/rspeedy/rspeedy.output.sourcemap.md), you can directly debug the original code you author in the Sources panel.

### Check If Source Maps Loaded Successfully

#### Check Load Status

When you open DevTool, it attempts to load source maps, if any.

After loading successfully, the files in the **File Navigator Pane** with orange folders are the original source files.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/original-files.png" alt="Original files" style={{ width: 500 }} />

If loading fails, the **Console** logs an error similar to the following.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sourcemap-fail.png" alt="Sourcemap fail" style={{ width: 500 }} />

When you open any compiled file, DevTool will notify you if it found the source map.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sourcemap-detected.png" alt="Sourcemap detected" style={{ width: 500 }} />

#### Load a Source Map Manually

You can manually load a source map:

1. Open the compiled file, right-click anywhere in the **Code Editor Pane**, and select **Add source map**.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/add-sourcemap1.png" alt="Add sourcemap1" style={{ width: 500 }} />
2. Enter the source map URL in the textbox, then click **Add**.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/add-sourcemap2.png" alt="Add sourcemap2" style={{ width: 500 }} />

### Debug with Source Maps

1. In the original file, you can [set breakpoints](#pause-code-with-breakpoints) as you normally would, or you can set breakpoints in the compiled file, and DevTool will automatically jump to the original file.
2. After triggering a breakpoint and pausing, the **Call Stack** pane will display the name of the original file.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/original-file-stack.png" alt="Original file stack" style={{ height: 400 }} />
3. The bottom status bar of the **Code Editor Pane** will show a link to the compiled file it points to. Click it to jump to the corresponding file.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sourcemap-from.png" alt="Sourcemap from" style={{ width: 500 }} />

## Debug the Main Thread

Debugging the main thread is similar to debugging the background thread, but it requires some additional steps to enable.

### Preparation

To debug the main thread, you need to start the project in **dev** mode using rspeedy.

You can check the following two items to ensure preparation is done:

1. A `debug-info.json` file is generated in the [intermediate output directory](/api/rspeedy/rspeedy.distpath.intermediate.md).
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/debug-info.png" alt="Debug info" style={{ height: 200 }} />
2. In the `tasm.json` file of the [intermediate output directory](/api/rspeedy/rspeedy.distpath.intermediate.md), the `templateDebugUrl` field is a valid URL pointing to the `debug-info.json` file mentioned in step one. Refer to [rspeedy.dev.assetprefix](/api/rspeedy/rspeedy.dev.assetprefix.md).
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/template-debug-url.png" alt="Template debug url" style={{ width: 600 }} />

### Enable Main Thread Debugging

Hover over the position shown in the image below, then enable **Main Thread Debugging**. This is a non-persistent global switch that takes effect for all pages during a single APP run. The switch state will be reset after closing and restarting the APP.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/main-thread-debugging.png" alt="Main thread debugging" style={{ height: 400 }} />

To enable main thread debugging:

1. Turn on the switch, then open the page you want to debug. Or open the page you want to debug, turn on the switch, and then [reload](/guide/devtool/panels/elements-panel.md#introduction-to-the-preview-panel) the page.
2. The `main-thread.js` file of the main thread will be displayed in the **File Navigator Pane** (formerly known as `lepus.js`).
3. In the **Threads** pane, switch to **Main** to start debugging.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/main-target.png" alt="Main target" style={{ height: 400 }} />

In the **Threads** pane, you can switch between debugging the main thread or the background thread. The blue arrow icon represents which context is selected. The currently paused thread will be marked as **paused**.

## Compatibility


### Breakpoints

**Error:** No compatibility data found for `devtool.panels.sources.breakpoints`
### JS Engine

**Error:** No compatibility data found for `devtool.panels.sources.JSEngine`


---
url: /guide/devtool/recorder.md
---

# Recorder

Recorder is a tool designed for the Lynx framework to facilitate the recording and replay of page runtime states. Its core functionality involves precisely capturing the complete state of a page at a specific moment and serializing it into a portable recording file for subsequent high-fidelity replay.

## What it does？

Unlike traditional screen recording technologies, Recorder achieves "Deterministic Replay." During the replay process, the system not only reconstructs the complete UI hierarchy and rendering data from the time of recording but also preserves all page interactivity. Crucially, it achieves temporal consistency by hijacking and mocking time-related APIs, ensuring that time-sensitive operations within the replayed environment yield the same results as they did during the original session.

Recorder features cross-device replay capabilities. Through its integrated Replayer decoder, a recording file can be parsed and replayed on any device that supports the Lynx framework, regardless of hardware model or operating system. For instance, a session recorded on an iPad can be accurately reproduced on an iPhone, an Android device, or even on desktop and TV applications built with the same Lynx technology stack.

## What can you use it for?

As an application's feature set expands, Lynx pages often become tightly coupled with the native application environment. This includes dependencies on custom NativeModules or private cloud services for data and resource management.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recorder_main_page.png" alt="device-connect" width={800} />

When diagnosing complex issues, this strong coupling becomes a major impediment to external collaboration and debugging, leading to problems such as build failures, complex authentication procedures, and inaccessible backend services. In such scenarios, traditional methods like code review are inefficient, while source-level debugging is often impractical due to environmental discrepancies.
A core design objective of Recorder is to decouple the page from its private environment. A recording file encapsulates all information required for the page to run, including the view hierarchy, data state, and responses from asynchronous requests. During replay, all external dependencies are simulated using the data contained within the recording file, eliminating the need for any live network requests. This makes the debugging process entirely independent of the original production environment.
Technical Advantages:

- Environment-Agnostic: Debuggers do not need to compile the original application, configure complex authentication, or set up specific development environments.
- Self-Contained Context: A single recording file contains all the necessary context to reproduce an issue.
- Efficient Collaboration: The party reporting the issue simply provides a recording file, allowing the recipient to debug in a standardized replay environment. This significantly reduces communication overhead and the difficulty of issue reproduction.

## Try Recorder

Recorder's record and replay capabilities are already integrated by default in LynxExplorer. You can follow the steps below to experience them.

<Steps>
  ### Download and install LynxExplorer

  Please visit [LynxExplorer](/guide/start/quick-start.md#prepare-lynx-explorer) and follow the documentation to run LynxExplorer app locally.

  ### Start record

  1. Connect the device to your PC via USB, and select the target application in the Tab.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recorder-device-connect.png" alt="device-connect" width={800} />

  2. Enter the Recorder plugin dashboard and click the Start button to activate.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/start-record.png" alt="start-record" width={800} />

  3. Operate on your phone, navigate to the target page you want to record and interact with it until it reaches the desired state.

  :::note
  It is especially important to note that, in order to ensure the completeness of the recorded page data, please make sure to click Start **before** navigating to the target page.
  :::

  Here is a sample page that you can access by scanning the QR code or entering the link in LynxExplorer.

  <Go img="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/galleryComplete.gif" example="gallery" defaultFile="src/GalleryComplete/index.tsx" defaultEntryFile="dist/GalleryComplete.lynx.bundle" highlight={{ 'src/GalleryComplete/index.tsx': '{6}' }} schema="{{{url}}}?bar_color=000000&back_button_style=dark&title=Popular Furniture&title_color=ffffff" />

  5. Click the Stop button to end the record.

  After stopping the record, the Recorder dashboard will automatically retrieve the recorded artifact from your device and provide a preview image to help you easily identify the target page.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/end-recordv2.png" alt="end-record" width={800} />

  ### Page Replay

  1. Artifact Hosting

  The Lynx DevTool Application only provides local file hosting for each recorded artifact. If you need to share the record artifact or access it across devices, you will need to host the artifact separately.

  2. Replay using LynxExplorer

  Here is a sample recorded artifact that you can replay by scanning the QR code or entering the link in LynxExplorer.

  <div
    style={{
  display: 'flex',
  justifyContent: 'center',
  alignItems: 'center',
  flexDirection: 'column',
}}
  >
    <QRCodeSVG style={{ border: '2px solid #fff' }} size={220} value="file://lynxrecorder?url=https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/LynxRecorder_2025-06-26T06_51_24.926Z.json" />

    <CopyToClipboard
      onCopy={() => {
    Toast.success('copy-link');
  }}
      text={
    'file://lynxrecorder?url=https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/LynxRecorder_2025-06-26T06_51_24.926Z.json'
  }
    >
      <Button type="tertiary" style={{ fontSize: '12px' }}>
        copy-link
      </Button>
    </CopyToClipboard>
  </div>

  :::note
  It is especially important to note that if you are using a self-hosted artifact URL for replay, you need to append the Recorder Header to the artifact URL to indicate that the artifact is from Recorder.

  Original artifact URL:

  ```txt
  https://lynx.recorder.artifacts/LynxRecorder.json
  ```

  Append the Recorder Header:

  ```txt
  file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json
  ```

  :::

  LynxExplorer can fully reproduce the recorded page.

  <div
    style={{
  display: 'flex',
  justifyContent: 'center',
  alignItems: 'center',
  flexDirection: 'column',
}}
  >
    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/replay.png" alt="replay-show" width={300} />
  </div>
</Steps>

## Integrate Recorder into your own application

<Steps>
  ### Switch to the dev version

  Since the record and replay process of Recorder covers the entire rendering process of Lynx and requires support from the underlying Lynx engine, we have released a separate dev version apart from the official Lynx release to prevent these record-related codes from affecting production environments. If you want to integrate Recorder, you need to change the version numbers of both Lynx and LynxDevtool in your project to the corresponding dev versions. [integrate lynx dev version](/guide/start/integrate-lynx-dev-version.md)

  ### Record capability integration

  The record capability can be integrated simply by using the dev version, with no additional adaptation required.

  ### Replay capability integration

  Recorder provides a highly encapsulated replay module, which is integrated into your application together with LynxDevTool. You only need to provide a simple entry point as described below.

  Choose your target platform to view the specific integration steps:

  <PlatformTabs queryKey="platform">
    <PlatformTabs.Tab platform="ios">
      1. In the Podfile, additionally include LynxRecorder for the LynxDevtool module.

      ```ruby
      pod 'LynxDevtool', lynxDevVersion, :subspecs => [
          'Framework',
          'LynxRecorder'
      ]
      ```

      2. Use LynxRecorderViewController to replay the recorded page.

      :::note Swift integration considerations

      LynxRecorder is written in Objective-C. If you want to call its methods from a Swift project, you need to provide a corresponding bridge file as described in [Importing Objective-C into Swift](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift).

      Add the following content to the bridge file:

      ```objective-c title="BridgeFile"
      #import <LynxDevtool/LynxRecorderViewController.h>
      ```

      :::

      <Tabs groupId="integrate-lynxrecorder-to-android">
        <Tab label="Objective-C">
          ```objective-c
          #import <LynxDevtool/LynxRecorderViewController.h>

          LynxRecorderViewController *recorderVC = [[LynxRecorderViewController alloc] init];
          recorderVC.url = @"file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json";
          UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:recorderVC];
          [self presentViewController:nav animated:YES completion:nil];
          ```
        </Tab>

        <Tab label="Swift">
          ```swift
          let recorderVC = LynxRecorderViewController()
          recorderVC.url = "file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json"
          present(recorderVC, animated: true, completion: nil)

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

    <PlatformTabs.Tab platform="android">
      1. Add a Recorder page entry

      <Tabs groupId="integrate-lynxrecorder-to-android">
        <Tab label="Java">
          ```java
          import android.app.Activity;
          import android.content.Context;
          import android.content.Intent;
          import android.os.Bundle;
          import com.lynx.devtool.recorder.LynxRecorderActivity;
          import com.lynx.devtool.recorder.LynxRecorderEnv;

          public class MainActivity extends Activity {
              @Override
              protected void onCreate(Bundle savedInstanceState) {
                  super.onCreate(savedInstanceState);
                  buildLynxRecorderView();
              }

              private LynxView buildLynxRecordView() {
                  String url = "file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json"
                  Intent intent = new Intent(this, LynxRecorderActivity.class);
                  intent.putExtra(LynxRecorderEnv.getInstance().mUriKey, url);
                  startActivity(intent);
              }

          }
          ```
        </Tab>

        <Tab label="Kotlin">
          ```kotlin
          import android.app.Activity
          import android.content.Context
          import android.content.Intent
          import android.os.Bundle
          import com.lynx.devtool.recorder.LynxRecorderActivity
          import com.lynx.devtool.recorder.LynxRecorderEnv

          class MainActivity :Activity() {

              override fun onCreate(savedInstanceState: Bundle?) {
                  super.onCreate(savedInstanceState)
                  buildLynxRecorderView()
              }

              private fun buildLynxRecordView() {
                  val intent = Intent(this, LynxRecorderActivity::class.java)
                  val url = "file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json"
                  intent.putExtra(LynxRecorderEnv.getInstance().mUriKey, url)
                  startActivity(intent)
              }

          }
          ```
        </Tab>
      </Tabs>

      2. Register LynxRecorderActivity in the app manifest file.

      ```xml
      // AndroidManifest.xml
      <activity
          android:name="com.lynx.devtool.recorder.LynxRecorderActivity"
          android:exported="false" />
      ```
    </PlatformTabs.Tab>

    <PlatformTabs.Tab platform="harmony">
      lynx\_devtool provides a highly encapsulated `LynxRecorderView` component that enables page replay by simply passing in the recorded artifact URL.

      ```tsx
      import { LynxRecorderView } from '@lynx/lynx_devtool';

      build() {
        Column() {
          LynxRecorderView({
            url: 'file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json'
          })
        }.size({ width: '100%', height: '100%' })
      }
      ```
    </PlatformTabs.Tab>
  </PlatformTabs>
</Steps>

## Compatibility


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

**Platform Support**

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

**Description:** Lynx Recorder Support




---
url: /guide/devtool/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




---
url: /guide/devtool/trace/js-profile.md
---

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


# Analysis JavaScript

Trace supports recording detailed JavaScript profile data. A JavaScript Profile is a collection of stack traces sampled during execution, which is crucial for pinpointing performance hotspots and bottlenecks. This allows you to analyze [script](/guide/spec.md#javascript-script) execution performance.

<Steps>
  ### Click `JS Profile` and Select the correct scripts engine

  Based on the background thread scripts engine used by your Lynx page, choose the appropriate value in the JS Profile selection.

  - disable: Do not enable JavaScript profiling;
  - [primjs](/guide/spec.md#primjs-vm): Enable profiling for the PrimJS JavaScript engine.
  - [v8](/guide/spec.md#v8-javascript-core-quickjs-hermes-etc): Enable profiling for the V8 JavaScript engine.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/choose-js-profile-type-latest.png" alt="Choose JS Profile Type" className="full_image" />

  ### Start recording

  Click `Start` button to begin recording trace.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/start-js-profile-trace-latest.png" alt="Start Recording JavaScript Profile" className="full_image" />

  ### Stop recording

  When finished, click `Stop` button to end the recording.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/stop-js-profile-trace-latest.png" alt="Stop Recording JavaScript Profile" className="full_image" />

  ### Decode JavaScript Profile Data using sourcemap (Optional)

  If your scripts is [minified](/api/rspeedy/rspeedy.minify.md), you can use [sourcemap](/api/rspeedy/rspeedy.sourcemap.md) to decode profile data.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/sourcemap-decode-latest.gif" alt="Decode JavaScript Profile" className="full_image" />
</Steps>

### FAQ

##### No JavaScript profile data after recording trace

- Make sure you have selected the correct script engine before starting recording.
- On iOS, ensure both Lynx DevTool and [PrimJS Debugging](/guide/start/integrate-lynx-devtool-advanced.md) are enabled.

##### No scripting resource found after clicking SourceMap Decode

- Ensure you start trace recording before opening the Lynx page so that the script resource name can be captured.



---
url: /guide/devtool/trace/launch-trace.md
---

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


# Record Trace During App Startup

Trace supports recording trace during the app startup process, which is essential for analyzing and optimizing app's start performance.

<Steps>
  ### Click Startup Trace

  In the topbar, click the `Startup Trace` button.

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

  ### Set duration (seconds)

  Enter the desired duration for recording trace during app startup. Press the `Enter` key to save your configuration.

  <img
    src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/startup-trace-dur-latest.png"
    alt="Startup Trace Duration"
    style={{
  width: '300px',
  margin: '20px',
}}
  />

  ### Restart application

  Close and relaunch your app. Trace will automatically record trace during the startup period.

  ### Load startup trace

  After the app launches, choose target app, then click the `Load Trace` button in Lynx DevTool.

  <img
    src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/load-startup-trace-latest.png"
    alt="Load Startup Trace"
    style={{
  width: '300px',
  margin: '20px',
}}
  />

  ### View the startup trace

  Once the trace data has loaded, you will see a visualization of the app’s startup process for detailed analysis.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/load-startup-trace-success-latest.png" alt="Load Startup Trace Success" className="full_image" />
</Steps>

### FAQ

##### After clicking `Load Trace` button shows: "Startup tracing is not enabled, cannot pull trace data"

- Make sure to set a valid trace duration (greater than 0) in Startup Trace Configuration, then restart the app and click `Load Trace` button again.
- Ensure a Lynx page is opened during or after the app startup process before clicking `Load Trace` button.

##### Clicking `Load Trace` button shows: "Startup tracing is in progress, please try again later"

- The app startup trace is still being recorded. Please wait for the process to finish and try clicking `Load Trace` button again later.



---
url: /guide/devtool/trace/record-trace.md
---

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


# Record Trace

This article aims to help you use DevTool to record Trace for Lynx pages. By following these steps, you will be able to capture detailed information about the page rendering process and engine execution, enabling effective performance analysis and problem diagnosis.

## Setup

1. Install [DevTool Desktop Application](/guide/devtool/panels.md#run-lynx-devtool-desktop-application).
2. Use the latest [LynxExplorer app](https://github.com/lynx-family/lynx/releases) or [integrate lynx dev version](/guide/start/integrate-lynx-dev-version.md) into your application.
3. Use a data cable to connect your device to your computer.

## Record Trace

<Steps>
  ### Select Trace

  Open the DevTool desktop application and choose `Trace` from the topbar.

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

  ### Select the app

  Pick the target app you want to profile from the available device list.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/select-target-app-latest.png" alt="Select Target App" className="full_image" />

  ### Start recording

  Press the `Start` button to start recording trace.

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

  ### Stop recording

  Click the `Stop` button to stop recording trace.

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

  ### Analyze

  After stopping, the trace data will be displayed for analysis.

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

  ### Download trace data(optional)

  If needed, click the `Download` button to save the trace file to your computer.

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

  ### View or manage historical trace data

  Click **History** button to see previous trace data.

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

  You can select a trace file to `view`, `download`, or `delete` as needed on Trace History panel.
</Steps>

### FAQ

##### After clicking `Start` button, the message "Current app does not integrate lynx and lynx-trace components with dev version, please integrate dev version first according to the following document" appears.

- Use the latest [LynxExplorer app](https://github.com/lynx-family/lynx/releases), or refer to [integrate lynx dev version](/guide/start/integrate-lynx-dev-version.md) to integrate the dev version of lynx.

##### After clicking `Start` button, the message "Tracing already started" appears.

- A trace recording is already in progress. Click `Stop` button to end it.

## Next Steps

<NextSteps.Root>
  <NextSteps.Step href="/guide/devtool/trace/launch-trace" title="Advance Usage" description="Explore advanced features like recording startup trace, JavaScript profiling, and custom trace events" />
</NextSteps.Root>



---
url: /guide/devtool/trace/trace-ui-basic-usage-guide.md
---

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


# Trace UI Basic Usage Guide

This guide introduces the main UI structure and common operations to help you quickly get started with performance analysis.

## UI Structure Overview

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace-ui-structure-overiview-3-5.png" alt="UI Structure Overview" className="full_image" />

The Trace UI consists of the following key components:{' '}

- Topbar: Includes a search box, SourceMap Decode, Focus LynxView, and other features.
- Timeline: Displays the occurrence and duration of TraceEvents. Supports adding annotations (notes), measuring intervals, and more.
- TrackTreeView: Organizes TraceEvents by track (typically one or more per thread), making it easy to distinguish between different threads/tasks.
- DetailPanel: Shows detailed information about a selected TraceEvent, including parameters, duration, thread, process, and more.

## Common Operations

### Open a Trace File

- Drag and drop a trace file directly onto the page for automatic parsing and display of trace.

### Zoom and Pan the Timeline

- Zoom in/out: Use the `w` (zoom in) and `s` (zoom out) keys.
- Pan left/right: Use the `a` (left) and `d` (right) keys.

### Search for TraceEvents

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/search-trace-event.PNG" alt="Search for TraceEvents" className="full_image" />

- Enter TraceEvent names, parameters, or keywords in the Topbar search box to quickly locate events.
- Press the `f` key to jump to the currently selected search result.
- Click the arrow at the end of the search box to jump to the previous/next result, or press Enter to move to the next result.
- The Timeline will highlight the currently selected search result for easy identification.

### View TraceEvent Details

- Click any TraceEvent in the Timeline to view its detailed parameters, duration, process, and thread information in the DetailPanel.

### Aggregate TraceEvents

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/aggregate-trace-event.PNG" alt="Aggregate TraceEvents" className="full_image" />

- Select a range of TraceEvents by dragging with the left mouse button across one or more tracks. Events will be aggregated by name.
- Aggregated results are shown in the DetailPanel, including total duration, average duration, and occurrence count.
- Click the column headers in the aggregation results to sort by name, total duration, average duration, or count.

### Add Timeline Annotations

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/add-timeline-annotations-latest.png" alt="Add Timeline Annotations" className="full_image" />

- Click on the Timeline to add a note at the corresponding position. Notes can be named for easier identification and navigation.

### Measure Time Intervals

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/measure-time-intervals.png" alt="Measure Time Intervals" className="full_image" />

- Click and drag on the Timeline to measure the interval between two points. This is useful for precisely analyzing the duration of tasks or operations.

### Focusing LynxView

Trace data may contain events from multiple Lynx pages. Trace supports focusing on one or more specific Lynx pages, making it easier to locate and analyze performance issues for particular pages.

<Steps>
  #### 1. Click Focus LynxView button

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/focus-lynxview-trace.png" alt="Force LynxView Button" className="full_image" />

  #### 2. Select the Lynx page(s) by URL

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/focus-lynxview-choose-trace-latest.png" alt="Force LynxView Choose" className="full_image" />

  After selecting the Lynx page(s), Trace events from unselected pages will be grayed out.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/focus-lynxview-after-trace-latest.png" alt="Force LynxView After Choose" className="full_image" />
</Steps>

### Querying Lynx Engine Version

Search for LynxEngineVersion or Version to find the Lynx Engine version.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/lynx-engine-version-trace.png" alt="Lynx Engine Version" className="full_image" />

### Querying the System Where the Trace Was Recorded

1. Enter a colon in the Topbar search box to enter SQL query mode;
2. Input the following SQL statement to query the system information where the Trace was recorded:

```sql
select name, str_value from metadata where name like "system%";
```

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

## Additional Resources

For a more detailed guide on using the Trace UI and its advanced features, please refer to the official Perfetto documentation: [perfetto-ui](https://perfetto.dev/docs/visualization/perfetto-ui)



---
url: /guide/embed-lynx-to-native.md
---

# Embedding LynxView into Native View

[LynxView](/guide/spec.md#lynxview) itself is a native view that can easily be used as a full-screen view, or be [embedded](/guide/spec.md#embedded) within a non-full-screen native view.

LynxView corresponds to the [Page](/api/elements/built-in/page.md) element. It only allows the client to set size constraints on LynxView, and you generally cannot directly modify the Page's style to set its size.

The client sets different size constraints on LynxView, which translates to setting size constraints on the Page.
The Lynx [layout engine](/guide/spec.md#starlight) uses these constraints to calculate the size of the Page node and all its child nodes.

## Constrain the size of LynxView \{#Constraining-LynxView}

### Constraint mode

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

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

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

### LynxView with fixed size


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

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

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

### LynxView with flexible size


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

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

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



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



---
url: /guide/inclusion/accessibility.md
---

# Accessibility


Accessibility (A11y) refers to the design concept of building accessibility through technical means to ensure that mobile applications can be equally accessed by all kinds of people.

Its core goal is to break down usage barriers, allowing users with different physical conditions, perceptual abilities, and cognitive levels to smoothly obtain information and services.

Mainstream mobile platforms provide a complete accessibility support system: iOS and Android not only natively integrate APIs for users with disabilities but also come equipped with standardized assistive technology toolchains, such as screen readers (VoiceOver / TalkBack) designed specifically for visually impaired users.

On this basis, the Lynx framework encapsulates cross-platform accessibility interfaces, enabling developers to integrate accessibility features in their apps and build an information-accessible mobile ecosystem.

:::info
Different platforms have distinct designs and norms regarding accessibility; therefore, implementation and experience with Lynx may vary across platforms.
:::

## Default Accessibility Behavior

Only one accessibility element can be successfully accessed and focused by screen readers (VoiceOver on iOS and TalkBack on Android).

However, `<text>` and `<image>` are default accessibility elements and can be recognized without any further action.

**This is an example below:  accessibility**

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

```tsx {4-5}
export const Default = ({ src }: { src: string }) => {
  return (
    <view>
      <text>Hello world</text>
      <image auto-size style="width:100px" src={src} />
    </view>
  );
};

```



## Tagging Accessibility Elements

Sometimes, you might want to control the size of accessibility elements or aggregate some accessibility information, requiring control over which elements are accessibility nodes.

Use [`accessibility-element`](/api/elements/built-in/view.md#accessibility-element) to tag an element as an accessibility element; nested elements are allowed.

In the example below, there will be only one accessibility focus point and it will be read as "Hello world".

**This is an example below:  accessibility**

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

```tsx {5,8,9}
export const Customized = ({ src }: { src: string }) => {
  return (
    <view
      style={{ padding: "10px" }}
      accessibility-element={true}
      accessibility-label={"Hello world"}
    >
      <text accessibility-element={false}>Hello</text>
      <text accessibility-element={false}>world</text>
    </view>
  );
};

```



:::info
On `<text>` and `<image>`, this property is set to `true` by default.
:::

## Specifying the Characteristics and Content of Accessibility Elements

Use [`accessibility-trait`](/api/elements/built-in/view.md#accessibility-trait) to mark the characteristics of an accessibility element, which can be any of image, button, or text.

Use [`accessibility-label`](/api/elements/built-in/view.md#accessibility-label) to adjust the content that screen readers will read for an accessibility element.

:::info
On `<text>`, the default is to read the content of the text.
:::

In the example below, the elements will be read as "Hello lynx" and "I am an image displaying the Lynx icon," respectively.

**This is an example below:  accessibility**

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

```tsx {6,7,16,17}
export const LabelAndTraits = ({ src }: { src: string }) => {
  return (
    <view
      style={{ padding: "10px" }}
      accessibility-element={true}
      accessibility-trait="button"
      accessibility-label={"Hello world"}
    >
      <text accessibility-element={false}>Hello</text>
      <text accessibility-element={false}>world</text>
      <image
        auto-size
        style={{ width: "100px" }}
        src={src}
        accessibility-element={true}
        accessibility-trait="image"
        accessibility-label="I am an image displaying the Lynx icon"
      />
    </view>
  );
};

```



## Adjusting the Reading Order of Accessibility Elements

iOS and Android systems default to arranging accessibility elements from top to bottom and left to right so they can be accessed sequentially by screen readers.

Use [`accessibility-elements`](/api/elements/built-in/view.md#accessibility-elements) to manually adjust this order. Note that each id should be separated by a comma.

Furthermore, if a parent node sets the [`accessibility-elements`](/api/elements/built-in/view.md#accessibility-elements) property, only child nodes specified by the [`accessibility-elements`](/api/elements/built-in/view.md#accessibility-elements) attribute can be accessed, while other child nodes cannot be focused.

In the example below, the order of accessibility elements will be adjusted, and they will be read as "Lynx" and "Hello" sequentially.

**This is an example below:  accessibility**

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

```tsx {3,5,6}
export const ReOrder = ({ src }: { src: string }) => {
  return (
    <view style={{ padding: "10px" }} accessibility-element={true} accessibility-elements="second,first">
      <view>
        <text id="first">Hello</text>
        <text id="second">Lynx</text>
      </view>
    </view>
  );
};

```



## Listening to Focus Changes of Accessibility Elements

When the focus of accessibility elements changes, a global event `activeElement` notifies the information of the newly focused node.

```tsx
export default class App extends Component<Props, State> {
  componentDidMount() {
    // Listen for focus changes
    this.getJSModule('GlobalEventEmitter').addListener(
      'activeElement',
      this.handleActiveElement,
      this,
    );
  }

  handleActiveElement(info: any) {
    this.setState({
      activeElementJsonStr: JSON.stringify(info),
    });
  }
}
```

## Actively Focusing on an Accessibility Element

Use [`requestAccessibilityFocus`](/api/elements/built-in/view.md#requestaccessibilityfocus) to provide the capability to actively focus on an accessibility element.

```ts
lynx
  .createSelectorQuery()
  .select('#customId')
  .invoke({
    method: 'requestAccessibilityFocus',
    params: {},
    success: function (res) {
      console.log(res);
    },
    fail: function (res) {
      console.log(res);
    },
  })
  .exec();
```

## Make Screen Readers Announce Specified Text Content

Use [`accessibilityAnnounce`](/api/lynx-api/lynx/lynx-accessibility-announce.md#accessibilityAnnounce) to make screen readers announce the specified text content, helping visually impaired users perceive interface state changes or operation results.

```jsx
lynx.accessibilityAnnounce(
  {
    content: 'hello lynx',
  },
  (res) => {
    console.log('test: ' + JSON.stringify(res));
  },
);
```



---
url: /guide/inclusion/internationalization.md
---

# Internationalization

**Internationalization** (i18n) refers to the design and development of products and applications to enable **localization**, making them suitable for users from different cultures, regions, or languages. You can use i18n libraries like `i18next` to achieve internationalization and provide an accessible experience for users.

## Intl API

The [`Intl`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl) object is a namespace for the ECMAScript Internationalization API, providing a set of methods for handling internationalization and localization. With the `Intl` API, you can handle issues related to numbers, dates, and times, such as number formatting and date and time formatting.

Currently, the `Intl` API is not implemented in Lynx but will be supported in future versions. If you need to use the `Intl` API in Lynx, you can install the corresponding polyfills, such as [@formatjs/intl-numberformat](https://www.npmjs.com/package/@formatjs/intl-numberformat), [@formatjs/intl-datetimeformat](https://www.npmjs.com/package/@formatjs/intl-datetimeformat), and [intl-pluralrules](https://www.npmjs.com/package/intl-pluralrules).

## Using `i18next`

[`i18next`](https://www.i18next.com/) is an internationalization-framework written in and for JavaScript. Using it in ReactLynx gives you:

1. **Simplicity**: `i18next` provides an easy-to-use API, making it simple to implement internationalization in ReactLynx applications.
2. **Dynamic Loading**: Supports on-demand loading of language resources, reducing initial load time.
3. **Wide Support**: Compatible with various formats and backends, allowing easy integration with different translation storage solutions such as JSON files, remote APIs, etc.
4. **Caching**: Built-in caching mechanism speeds up the loading of language resources, enhancing user experience.
5. **Rich Community Support**: A vast community and a wealth of plugins available to meet diverse internationalization needs.
6. **Reliability**: Proven in numerous projects, offering stability and reliability.
7. **Hot Reloading**: Changes to language resources can take effect immediately without needing to republish the application.

### Installation

You need to install the `i18next` package:

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

```





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

# Event Handling

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

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

## What is an event

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

**Example 1:**

**This is an example below:  event**

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

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

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

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

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

root.render(<App />);

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

```



## Listen for user clicks

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

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



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

# Event Propagation

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

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

## Event handler property

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

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

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

## Event response chain

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

**Example 1:**

**This is an example below:  event**

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

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

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

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

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

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

root.render(<App />);

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

```



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

## Event capture

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

**Example 2:**

**This is an example below:  event**

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

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

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

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

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

root.render(<App />);

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

```



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

## Event bubble

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

**Example 3**

**This is an example below:  event**

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

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

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

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

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

root.render(<App />);

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

```



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

## Event interception

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

**Example 4**

**This is an example below:  event**

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

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

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

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

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

root.render(<App />);

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

```



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

## Prevent Event Propagation in Main Thread Script

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

**Example 5:**

**This is an example below:  event**

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

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

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

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

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

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

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

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

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

root.render(<App />);

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

```



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

## Cross-component event listening <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();
}

```





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

# Direct Manipulation of Elements

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

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

## Manipulating Elements in Background Thread

### Example: Auto-scrolling

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

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

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

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

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

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

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

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

```



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

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

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

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

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

### Manipulating an Element via Its Reference

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

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

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

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

## Manipulating Elements in Main Thread

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

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

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

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

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

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

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

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

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

```



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

## Obtaining Element References via Selectors

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

### Background Thread

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

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

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

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

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

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

```



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

### Main Thread

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

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

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

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

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

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

```



## Obtaining a Reference to the Event Target Element

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

### Main Thread

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

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

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

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

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

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

```



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

## Using `getElementById` API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



---
url: /guide/interaction/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.



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

# Networking

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

## Using Fetch

:::tip

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

:::

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

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


**This is an example below:  networking**

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

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

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

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

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

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

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

root.render(<App />);

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

```



### Making Requests

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

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

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

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

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

### Handling the Response

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

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

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

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

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

## Using TextCodecHelper

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

Usage:

Convert `arraybuffer` to `string`:

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

Convert `string` to `arraybuffer`:

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

## Using Other Networking Libraries

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

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

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



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




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

# Visibility detection

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

## Detect whether a node is exposed

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

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

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

**Example 2:**

**This is an example below:  event**

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

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

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

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

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

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

root.render(<App />);

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

```



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

## Detect whether nodes intersect

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

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

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

**Example 1:**

**This is an example below:  event**

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

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

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

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

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

root.render(<App />);

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

```



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

## Summary

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

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



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

# Exposure Ability

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

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

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

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

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



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

# Intersection Observer

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

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

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

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

**This is an example below:  event**

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

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

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

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

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

root.render(<App />);

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

```



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



---
url: /guide/performance/analysis-performance.md
---

# Performance Analysis

This section guides you through performance analysis methodologies, from diagnosing rendering latency and instrumenting business logic to optimizing page fluency and memory usage, enabling comprehensive smoothness and stability improvements.

## Rendering Latency Analysis

### Record Trace data

Use [Devtool](/guide/devtool/trace/record-trace.md) to record Trace data. The Trace is presented on a [timeline](/guide/performance/analysis-performance/trace-track.md), capturing the full Lynx rendering pipeline, which lays the foundation for subsequent analysis.

### Analyze rendering latency

On the [Rendering-time analysis](/guide/performance/analysis-performance/analysis-render-process.md) page, combine Trace data to review first-frame rendering and page update flows, pinpoint time-consuming stages and performance bottlenecks along the rendering path. The [NativeModule invocation](/guide/performance/analysis-performance/analysis-native-module.md) page explains the complete execution flow of NativeModule calls to help you analyze them efficiently.

### Add custom instrumentation

Trace allows developers to add [custom Trace instrumentation](/guide/performance/analysis-performance/trace-api.md). Insert Trace events into key business flows, component lifecycles, and asynchronous tasks to visualize them on the Trace UI timeline, enabling precise tracking and localization of potential bottlenecks.

## Memory Analysis

The [Memory analysis](/guide/performance/analysis-performance/analysis-memory.md) page describes how to use Trace and IDE tools to analyze memory peaks, growth trends, and abnormal leaks, helping developers discover and fix memory issues early to improve application stability.

## Fluency

The [Fluency analysis](/guide/performance/analysis-performance/analysis-fluency.md) page explains how to analyze dropped frames and jank, enabling developers to quickly locate and optimize page interaction performance.



---
url: /guide/performance/analysis-performance/analysis-fluency.md
---

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

# Fluency Analysis

When scrolling occurs, the system attempts to draw the next frame at a fixed cadence; any noticeably longer draw interval will be perceived by users as a “stutter” or “jitter.” These momentary long frames are the source of “dropped frames.” Scrolling is the most cadence-sensitive scenario, because backgrounds, text, and images are continuously moving; once the beat becomes unstable, the eye immediately notices.

## Offline Trace analysis

Offline Trace aims to reconstruct the frame timing of a scrolling interaction, tie “which segment dropped frames” to “why it dropped,” and produce actionable fixes. For Trace capture, see [Record Trace](/guide/devtool/trace/record-trace.md) and ensure the capture covers the full scrolling time window and realistic scroll speed.

### How Trace displays dropped frames

In the Trace webpage, frame render time labels were added at the start of `Choreographer#doFrame` (currently Android only). These labels display dropped-frame situations throughout the entire system render process. By observing these labels, you can visually identify render-time anomalies. Frame render time is computed by summing the time spent in `Choreographer#doFrame` on the UI thread and `DrawFrames` on the `RenderThread`. If the total is ≥ 32 ms, the label is red; if the total is ≥ 16 ms and \< 32 ms, the label is orange; if the total is \< 16 ms, the label is green. For offline analysis, treat frames marked red or orange as the tasks most likely causing dropped frames and analyze them preferentially.

<img className="full_image" alt="Frame Rendering Time" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/20250929-163554.jpeg" />

### Locating dropped-frame segments during scrolling

- On the timeline, look for frames that clearly exceed the cadence (for example, consecutive red labels) and mark them as “long-frame segments.”
- Analyze frame by frame to confirm whether the cause is UI-thread congestion, delayed render submission, or resource loading/decoding inserted into the critical path.
- Associate long-frame segments with UI elements (large images, complex list items, card animations) to form actionable ties to what users see.

### Root-cause patterns and identification

- UI thread blocking: layout and measurement stacking, or I/O running on the UI thread.
- Heavy layout and drawing: deep hierarchies, frequent reflow, or large-area repaint; concentrated text and image size computation; complex `Canvas` drawing. Symptom: a single frame’s computation time is unusually long and repeats with scroll.
- Image and resource loading: decode, downsample, and texture upload blocking critical frames; async not truly isolated, or missing placeholders/preload. Manifestations: `GPU` or `RenderThread` queues back up, correlated with image size or count.

### Common investigation suggestions

- Reduce UI-thread workload: move non-essential computation and I/O off the UI thread; spread layout and drawing across frames to avoid “everything in a single frame.”
- Optimize layout depth and measurement: control hierarchy depth and constraints complexity; avoid repeated measurement; use compositing layers to reduce unnecessary repaint.
- Image and resource governance: constrain dimensions and size, use placeholders and preload; move decode and texture upload earlier or run in parallel; load on demand and reuse caches.
- JS and bridge: split long tasks and reduce synchronous calls; use throttling and batching to avoid high-frequency messages overwhelming the UI cadence.



---
url: /guide/performance/analysis-performance/analysis-memory.md
---

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


# Memory Usage Analysis

Memory analysis helps discover leaks and abnormal usage within Lynx pages and ensures stability. You can use Trace Memory Track and IDE tools, to comprehensively monitor and troubleshoot memory-related performance issues.

## Deep analysis with Trace

Starting from 3.4, Trace supports Memory Track, which shows Lynx page memory usage trends over time. Each Memory Track represents one Lynx page’s memory changes.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/memory-track-latest.png" alt="Memory Track" className="full_image" />

Click the Memory Track curve to see the page’s total memory usage and the memory used by Element, background scripting engine, main-thread scripting engine, images, etc.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/memory-track-details.png" alt="Memory Track Detail" className="full_image" />

## Analyze memory with IDEs

This section briefly introduces how to use Android Studio or Xcode’s built-in tools to debug apps and view performance metrics.

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    This section introduces how to analyze memory using Xcode.

    ### Analyze (static check)

    Choose Product > Analyze or press Shift + Command + B to run automatically. Analyze uses syntax and memory context to find potential issues. It mainly detects four categories:

    1. Logic errors: dereferencing null pointers, uninitialized variables.
    2. Memory management errors: e.g., memory leaks.
    3. Declaration errors: variables never used.
    4. API call errors: missing libraries or frameworks.

    :::tip
    📌 Analyzer makes compiler-driven judgments and is not always accurate. If you see a report, review surrounding code; some cycle references that cause memory leaks cannot be identified by Analyzer. Analyzer makes compiler-driven judgments and is not always accurate. If you see a report, review surrounding code; some cycle references that cause memory leaks cannot be identified by Analyzer.
    :::

    ### Leaks (dynamic check)

    Xcode > Open Developer Tool > Instruments > Leaks

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-12.png" alt="Leaks dynamic check" className="full_image" />

    Choose Leaks, then specify the device and app to debug. In this example, an iPhone SE2 (iOS 14.5) simulator debugs the LynxExample app. Click the start button to check for memory leaks.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-13.png" alt="Leaks Start Button" className="full_image" />

    After starting, operate in the simulator or on device. If the Leaks window shows issues, jump to the corresponding code to debug. You can pause to inspect memory info shown in the chart. After debugging, you can save the results locally.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-14.png" alt="Leaks Analysis Result" className="full_image" />

    If a memory leak appears (example below), set the chart to Call Tree mode, then enable Invert Call Tree at the bottom of the window. Select any leak to jump to source code.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-15.png" alt="Leaks Call Tree Mode" className="full_image" />

    ### Allocations (detailed allocation)

    Xcode > Open Developer Tool > Instruments > Allocations

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-17.png" alt="Allocations Tool" className="full_image" />

    Similar to Leaks but focuses on detailed memory allocations. The lower list shows per-method memory usage. Check a graph to show a bar chart above. Click an item to view stack trace details; click the right-hand Stack Trace pane to jump into code and inspect allocations.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-18.png" alt="Allocations Stack Info" className="full_image" />

    The code section is highlighted and the allocation ratio is shown.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-19.png" alt="Allocations" className="full_image" />

    ###
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    This section introduces how to analyze memory using Android Studio.

    ### Profiler basics

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-1.png" alt="Profiler Tool" className="full_image" />

    First click the highlighted area in the toolbar; Android Studio performs a Build and then opens the Profiler window. From there you can run tests—click the ‘+’ icon to select a device connected via adb and the process to test.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-2.png" alt="Profiler Choose Process" className="full_image" />

    Using a Xiaomi MIX (API 24), we run a \~45 s test and manually trigger a GC at 15 s. From left to right, the icons are GC, Capture Heap Dump, and manual Record (an option for devices below API 26 for memory analysis).

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-3.png" alt="Profiler Tool Record" className="full_image" />

    Over 45 s, the device’s memory changes are as follows:

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-4.png" alt="Profiler Tool Record" className="full_image" />

    In this example, after the manual GC, the app’s memory usage drops noticeably for a period.

    Heap dumps show which objects are using memory at the time of capture. Especially after long user sessions, heap dumps reveal objects that should no longer be in memory, helping identify leaks. After clicking the Heap Dump icon, Java memory may temporarily increase because dumping runs in the same process and needs memory to collect data.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-5.png" alt="Profiler Memory Status" className="full_image" />

    After capturing the heap dump, use the built-in analyzer. The table shows:

    - Allocations: number of allocations in the heap.
    - Native Size: total native memory used by this object type (Bytes). Visible on Android 7.0+ only. Some Java-allocated framework classNames (e.g., Bitmap) consume native memory.
    - Shallow Size: total Java memory used by this object type (Bytes).
    - Retained Size: total memory retained by all instances of this className (Bytes).

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-6.png" alt="Profiler Memory Detail" className="full_image" />

    Click a className in the chart to open the Instance List window, then jump to source for inspection.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-7.png" alt="Profiler Source Info" className="full_image" />

    Or use the Reference window for more detailed checks and jump elsewhere for inspection.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-8.png" alt="Profiler Source Transfer" className="full_image" />

    After capturing a heap dump, you can also export hprof data from the SESSIONS window via Export Heap Dump. Use other tools (such as MAT) to further analyze the heap.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-9.png" alt="Profiler Memory Dump" className="full_image" />

    ### Memory profiler

    On devices below API 26, you need to manually record a time window before running memory performance analysis. Use the filter options (red circle) such as Arrange by className. In the table, select a className to jump to the Instance View, then to Allocation Call Stack to view stack traces and jump to source.

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-10.png" alt="Memory profiler" className="full_image" />

    ### Symptoms of memory leaks

    - Many Full GCs during runtime.
    - During a specific thread’s execution, manual GC has little effect.
    - Many allocations and frees in a short time (memory graph jitter).

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-11.png" alt="Memory profiler" className="full_image" />

    ### Example leak and related analysis

    ```java
    final className LoadedInChildClassLoader {

      static final byte[] moreBytesToLeak = new byte[1024 * 1024 * 100];

      private static final ThreadLocal<LoadedInChildClassLoader> threadLocal
              = new ThreadLocal<>();

      public LoadedInChildClassLoader() {
        threadLocal.set(this);
      }
    }
    ```

    #### Methods to trigger potential leaks

    Apply pressure to app code and try to force leaks while cross-checking with the memory profiler. One way to induce leaks is to let the app run for some time, then inspect the heap; leaks may accumulate near the top of allocation. The smaller the leak, the longer the app needs to run to reveal it.

    - Rotate the device repeatedly to trigger potential leaks.
    - Switch between the debug app and other apps across different Activity states (e.g., go Home then return).

    #### Possible causes of leaks

    - Long-running threads.
    - A thread loads a className via the ClassLoader.
    - A className allocates large memory.
    - A thread clears references to all custom classNames and the ClassLoader that loaded them.
  </PlatformTabs.Tab>
</PlatformTabs>

## Performance testing with PerfDog

PerfDog is a third-party tool for checking Android and iOS app performance and is easy to use. After connecting a device and choosing the app to debug, click the red circled plus button at the bottom right to add performance parameters before starting.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-20.png" alt="PerfDog Tool" className="full_image" />

After the test, you can save data as a table and view performance parameters such as Jank count. Use the tool’s metrics as simple references to check app performance.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-21.png" alt="PerfDog Save Data" className="full_image" />



---
url: /guide/performance/analysis-performance/analysis-native-module.md
---

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

# NativeModule Invocation

NativeModule is the core communication bridge between JavaScript and native applications. By invoking a NativeModule, Lynx frontend pages can access and control native capabilities. This document together with code examples, details the invocation and execution flow of NativeModule within Trace.

## Deep analysis with Trace

Since Lynx 3.2, the Trace page includes a NativeModule Track that aggregates all NativeModule invocations. Each item’s length reflects the overall duration from request initiation to completion.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-track.png" />

Basic display: click an item in the NativeModule Track to view a color-coded breakdown of rough durations for each stage of the invocation.

Details panel: shows the method name, input parameters, and precise per-stage durations (including parameter conversion, platform logic, thread switches, and other key nodes).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-timing-stage.png" />

## Breakdown of NativeModule invocation details

Below we use a frontend NativeModule call as an example to describe execution timing in Trace.

### Example code

```ts {4,5,6,7,10}
NativeModules.bridge.call(
  'setStorage',
  {
    data: {
      key: 'lynx_nativemodule_test',
      value: i,
    },
  },
  (res) => {
    console.log('setStorage res is: ', res);
  },
);
```

### Trace execution analysis

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-normal.jpeg" />

A NativeModule call can be divided into five main stages:

#### 1. Parameter conversion

This stage corresponds to `JSValueToPubValue` in Trace, where JS data (lines 4–7 in the code sample) is converted into native types.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-1.png" />

#### 2. Platform-layer implementation

This stage corresponds to the time period in the Trace from the start of `CallPlatformImplementation` to `NativeModule::PlatformCallbackStart`, where the native method executes the specific functionality and returns platform-layer data.

Among them, the `CallPlatformImplemention` occurs on the [background thread](/guide/spec.md#background-scripting-thread-historically-known-as-js-thread), while the logic between the `CallPlatformImplementation` event and `NativeModule::PlatformCallbackStart` usually runs on other threads.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-2.png" />

#### 3. Waiting for the background thread to execute the callback

This stage corresponds to `NativeModule::PlatformCallbackStart` and `NativeModule::Callback` in Trace.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-3.jpeg" />

#### 4. Result conversion

This stage corresponds to `PubValueToJSValue` in Trace, where platform-layer return data is converted into JS arguments.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-4.png" />

#### 5. Callback execution

This stage corresponds to `InvokeCallback` in Trace, which executes JS code logic (line 10 in the sample).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-5.png" />

## Special NativeModule calls

Currently, JSB SDKs in the company return results via callbacks. Some NativeModule implementations return results directly to the Lynx SDK via callbacks on the background thread. Callback execution is not necessarily limited to the main thread—any thread may invoke and execute callback-related logic.

### Example code

```js {4,5,6,9}
NativeModules.bridge.call(
  'x.reportAppLog',
  {
    data: {
      eventName: 'lynx_nativemodule_test_event_name',
    },
  },
  (res) => {
    console.log('reportAppLog res is: ' + JSON.stringify(res));
  },
);
```

### Trace execution analysis

These special NativeModule calls can be divided into five main stages.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special.jpeg" />

#### 1. Parameter conversion

This stage corresponds to `JSValueToPubValue` in Trace, where JS data (lines 4–6 in the sample) is converted into native types.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-1.jpeg" />

#### 2. Platform-layer implementation

This stage corresponds to the time period in the Trace from `CallPlatformImplementation` to the start of `NativeModule::Callback`, where the native method executes the specific functionality and returns platform-layer data.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-2.jpeg" />

#### 3. Result conversion

This stage corresponds to `PubValueToJSValue` in Trace, where platform-layer return data is converted into JS arguments.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-3.jpeg" />

#### 4. Callback execution

This stage corresponds to `InvokeCallback` in Trace, which executes JS code logic (line 9 in the sample).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-4.jpeg" />

#### 5. Cleanup

This stage corresponds to the time period in the Trace from the end of `InvokeCallback` to the end of `NativeModule::Invoke`, where platform-layer cleanup is performed and external registrants are notified that the NativeModule call has completed.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-5.jpeg" />



---
url: /guide/performance/analysis-performance/analysis-render-process.md
---

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


# Render Time Analysis

This document aims to help developers master how to accurately locate each execution stage in a Trace, thereby enabling effective analysis of specific performance issues.

## Analyze render time with Trace

Frontend pages can [flag Pipeline](/guide/performance/monitor-performance/timing-flag.md) for key components. When the component finishes rendering on screen, the [Timing Track](/guide/performance/analysis-performance/trace-track.md) in Trace generates a bubble at the corresponding timestamp to mark the key stage.

A Lynx page generally has two render types: first-frame rendering and update rendering. Internally, the Lynx SDK produces [LoadBundleEntry](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md) and [PipelineEntry](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) to describe stage durations in each process.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_overview.png" />

Click a bubble to open a details panel showing the sub-stage timeline and the duration of each sub-stage in the render process.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_detail_panel.png" />

The following sections detail both render types and their constituent stages, including the corresponding Trace event names, so you can locate and troubleshoot issues via Trace events.

## First-frame render time analysis

First-frame rendering primarily consists of LoadBundle and Paint:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_load_bundle.png" />

### LoadBundle

This stage corresponds to `Timing::Mark.loadBundleStart` and `Timing::Mark.loadBundleEnd` in Trace. It mainly parses the bundle and performs the initial screen render. It can be broken down into six sub-stages:

#### Parse

This stage corresponds to `Timing::Mark.parseStart` and `Timing::Mark.parseEnd` in Trace. It parses the binary bundle into in-memory data structures. The bundle contains a header and multiple sections; the JS source section runs on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread), mapped to `Timing::Mark.loadBackgroundStart` and `Timing::Mark.loadBackgroundEnd` in Trace.

#### MTS Render

This stage corresponds to `Timing::Mark.mtsRenderStart` and `Timing::Mark.mtsRenderEnd` in Trace. It executes [Main Thread Script (MTS)](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree.

#### Resolve

This stage corresponds to `Timing::Mark.resolveStart` and `Timing::Mark.resolveEnd` in Trace. It traverses the element tree, computes a layout node tree from node attributes and styles, and generates [UI Paint OP](/guide/spec.md#platform-ui-paint-operations-or-ui-paint-op).

#### Layout

This stage corresponds to `Timing::Mark.layoutStart` and `Timing::Mark.layoutEnd` in Trace. It traverses the layout node tree produced during Resolve, computes node positions and sizes, and generates [UI Layout OP](/guide/spec.md#platform-ui-layout-operations-or-ui-layout-op).

#### Paint UI OP Execute

This stage corresponds to `Timing::Mark.paintingUiOperationExecuteStart` and `Timing::Mark.paintingUiOperationExecuteEnd` in Trace. It executes the UI Paint OP generated during Resolve.

#### Layout UI OP Execute

This stage corresponds to `Timing::Mark.layoutUiOperationExecuteStart` and `Timing::Mark.layoutUiOperationExecuteEnd` in Trace. It executes the UI Layout OP generated during Layout.

### Paint

The system drawing stage measures, lays out, and paints the platform UI tree. The end of painting maps to `Timing::Mark.paintEnd` in Trace.

## Update render time analysis

Update renders are primarily driven by the background thread to update and draw the UI tree. The main difference from first-frame rendering lies in [Framework Rendering](/guide/spec.md#framework-rendering). Using ReactLynx 3 as an example, we highlight the differing parts:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_pipeline_entry.png" />

### Diff Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.diffVdomStart` and `Timing::MarkFrameWorkTiming.diffVdomEnd` in Trace. It performs component diff on the background thread.

### Pack Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.packChangesStart` and `Timing::MarkFrameWorkTiming.packChangesEnd` in Trace. It serializes diff results and sends them to the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread).

### Parse Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.parseChangesStart` and `Timing::MarkFrameWorkTiming.parseChangesEnd` in Trace. It parses the serialized data on the main thread.

### Patch Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.patchChangesStart` and `Timing::MarkFrameWorkTiming.patchChangesEnd` in Trace. It applies the diff results on the main thread and updates the Element Tree.

Subsequent render stages are similar to the first-frame process: Resolve, Layout, Paint UI OP Execute, Layout UI OP Execute, and Paint.

## Next Steps

<NextSteps.Root>
  <NextSteps.Step href="/guide/performance/analysis-performance/reactlynx-render-process" title="ReactLynx Render Pipeline" description="Understanding the ReactLynx Rendering Pipeline" />
</NextSteps.Root>



---
url: /guide/performance/analysis-performance/reactlynx-render-process.md
---

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

# ReactLynx Rendering Pipeline

This article uses the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project as an example to explain the ReactLynx rendering process in detail:

- Demonstrate the complete execution flow from the first-frame render to component updates in ReactLynx
- Understand the event distribution and timing relationships of each key stage in the Trace view
- Learn how to use the Trace tool to accurately locate performance bottlenecks in the rendering process

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

## First Screen Rendering

[First Screen Rendering](/guide/spec.md#first-screen-rendering-or-fsr) includes stages such as downloading the [Bundle](/guide/spec.md#lynx-bundle-or-bundle), loading the bundle, and drawing.

### Download Bundle

After the page starts, it first [downloads](/guide/spec.md#load) the Bundle。

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

### Load Bundle

Once the bundle is downloaded, it enters the loading stage.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/first-screen-render-pipeline-in-trace-latest.png" alt="Trace Render Pipeline" className="full_image" />

#### Parse Bundle

During the bundle loading stage, the content of the bundle—such as CSS stylesheets, scripts, and page configurations—is first [parsed](/guide/spec.md#parse)

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

#### Execute MTS

After parsing the bundle, the [Engine thread](/guide/spec.md#engine-thread-historically-known-as-tasm-thread) virtual machine executes the [MTS](/guide/spec.md#main-thread-script-or-mts).

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

#### Execute BTS

Meanwhile, the [background thread](/guide/spec.md#background-scripting-thread-historically-known-as-js-thread) virtual machine loads, parses, and executes the [BTS](/guide/spec.md#background-thread-script-or-bts).

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/backgound-script-execute-latest.png" alt="Execute Background Script" className="full_image" />

During BTS execution, you can observe the creation process of components.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/background-thread-create-component-thread-latest.png" alt="Background Thread Create Component" className="full_image" />

:::tip
The background thread does not block the Engine thread’s Element tree construction, resolve, layout, and other flows.
:::

#### Construct the Element Tree

During the [Element tree](/guide/spec.md#element-tree) construction stage, the [Element PAPI](/guide/spec.md#element-papi) is called to convert the page structure into an Element tree.

Taking the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project as an example, the first frame creates 1 page element, 6 view elements, 2 image elements, and 5 text elements.

```html
<page>
  <view className="Background" />
  <view className="App">
    <view className="Banner">
      <view className="Logo" bindtap={onTap}>
        <image src={lynxLogo} className="Logo--lynx" />
      </view>
      <text className="Title">React</text>
      <text className="Subtitle">on Lynx</text>
  </view>
  <view className="Content">
    <image src={arrow} className="Arrow" />
    <text className="Description">Tap the logo and have fun!</text>
    <text className="Hint">
      Edit<text style={{ fontStyle: "italic" }}>{" src/App.tsx "}</text>
      to see updates!
    </text>
  </view>
  <view style={{ flex: 1 }}></view>
  </view>
</page>
```

In Trace, you can observe the complete process of creating Elements and setting their Events, Classes, and other attributes.

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

#### Resolve

During the [Resolve](/guide/spec.md#resolve) stage, the Element’s className, inline styles, and other attributes are parsed to determine the Element’s style, and the [layout node tree](/guide/spec.md#layout-node-tree) is created.
As shown below, the Resolve stage covers the complete execution flow and the parsing of styles for `<view className="Background" />`.

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

#### Layout

The [layout](/guide/spec.md#layout) stage measures and lays out the layout nodes. The following example shows the layout process of the `<text>Tap the logo and have fun!</text>` node.

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

#### Flush

After the layout is complete, [platform UIs](/guide/spec.md#platform-ui) are created, with various attributes and layout information set.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/create-platform-ui-trace.png" alt="Create Platform UI" className="full_image" />

:::tip
Element nodes containing only layout attributes will not create platform UI nodes.
[Nested text](/api/elements/built-in/text.md#嵌套text) will be merged with their parent text node to create a single platform UI.
::

In the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project, the following nodes create platform UI on the first screen:

```html
<page>
  <view className="Background" />
  <view className="Banner">
    <view className="Logo" bindtap="{onTap}">
      <image src="{lynxLogo}" className="Logo--lynx" />}
    </view>
  </view>
  <text className="Title">React</text>
  <text className="Subtitle">on Lynx</text>
  <image src="{arrow}" className="Arrow" />
  <text className="Description">Tap the logo and have fun!</text>
  <text className="Hint"> Edit " src/App.tsx " to see updates!</text>
</page>
```

### Draw

When the system’s rendering callback occurs, the platform UI completes its first-screen drawing.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/draw-in-trace.png" alt="Draw Platform UI" className="full_image" />

## Update Rendering Process

Taking the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project as an example, clicking the Logo triggers an update, which demonstrates the component update rendering flow.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/reactlynx-re-rendering-trace.png" alt="Draw Platform UI" className="full_image" />

### Trigger the Click Event

After clicking the Logo, LynxView processes the [click event](/guide/spec.md#event-propagation) and sends the event to the background thread, triggering the corresponding node’s click [event handler](/guide/spec.md#event-handler).

To better observe the execution timing of the click event callback in Trace, you can use the [Trace API](/guide/performance/analysis-performance/trace-api.md) to add custom Trace events.

```javascript {3,5}
const onTap = useCallback(() => {
  'background only';
  lynx.performance.profileStart('onTap');
  setAlterLogo(!alterLogo);
  lynx.performance.profileEnd();
}, [alterLogo]);
```

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/touch-event-trace.png" alt="Touch Event Process" className="full_image" />

The App component updates the state of alterLogo in the click event callback.

### Diff Component Diff

After updating the component state, the component diff process is triggered, and the image node changes:

```html
<view className="Logo" bindtap="{onTap}">
  + <image src="{reactLynxLogo}" className="Logo--react" /> - -
  <image src="{lynxLogo}" className="Logo--lynx" />
</view>
```

The following image shows the diff process for the App component:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/component-diff-process.png" alt="Component Diff Process" className="full_image" />

### Component Update Synchronization

After the component diff is complete, the update information is synchronized to the Engine thread, driving subsequent UI changes. In Trace, clicking the `CallLepusMethod` event allows you to see the UI update process after component diff is complete.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/sync-change-to-ui-thread-latest.png" alt="Sync Diff To UI Thread" className="full_image" />

### UI Update

The Engine thread shows the update process of the Element tree. As shown below, the Element tree removes one element and adds a new image element.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/element-update-process.png" alt="Sync Diff To UI Thread" className="full_image" />

After the Element update is complete, the layout and UI are updated again.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ui-update-process.png" alt="Sync Diff To UI Thread" className="full_image" />

### Trigger useEffect Callback

After the Element tree update is complete, the background thread is notified to trigger the component’s useEffect callback.

To better observe the execution timing of the useEffect callback in Trace, use the [Trace API](/guide/performance/analysis-performance/trace-api.md) to add custom trace events.

```javascript {6-8}
useEffect(() => {
  console.info('Hello, ReactLynx');
}, []);

useEffect(() => {
  lynx.performance.profileMark('useEffect', {
    args: { alterLogo: `${alterLogo}` },
  });
}, [alterLogo]);
```

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/useeffect-callback-trace.png" alt="useEffect Callback" className="full_image" />



---
url: /guide/performance/analysis-performance/trace-api.md
---

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


# Using Trace API

Trace allows you to add custom trace events to your code, helping you track specific operations or logic flows. This is useful for profiling custom business logic, measuring durations, or marking important points in your app.

- For Frontend Developers: You might want to measure the execution timing of a hook or component lifecycle method to understand rendering delays or side effect durations. For example, tracking how long a `useEffect` hook takes;
- For Android/iOS Developers: You may want to profile how long it takes to load a Lynx Bundle, parse resources, or execute a specific NativeModule call. Custom trace events help you pinpoint slow operations within complex workflows;

By adding custom trace events, you transform opaque code sections into visible, measurable segments in Trace’s timeline, enabling precise performance tuning.

## How to Use

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    ### Slice Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png" alt="Slice Events" className="full_image" />

    - Definition: Slice events have both a start and end timestamp, representing a duration.
    - Nesting: On the same thread, slice events can be nested like a call stack.
      - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
      - Important: Child events must always end before their parent ends (i.e., B must end before A).
    - Use case: Suitable for profiling code sections where execution time matters.

    ```objc {3,5,10,12}
    // Basic usage
    - (void)measure {
      [LynxTraceEvent beginSection:@"render" withName:@"measure"]; // 'measure' slice start
      // ... your code ...
      [LynxTraceEvent endSection:@"render" withName:@"measure"]; // 'measure' slice end
    }

    // With custom arguments
    - (void)draw {
      [LynxTraceEvent beginSection:@"render" withName:@"draw-image" debugInfo:@{@"component": @"Image", @"size": @"large"}];
      // ... your code ...
      [LynxTraceEvent endSection:@"render" withName:@"draw-image"];
    }
    ```

    ### Instant Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png" alt="Instant Events" className="full_image" />

    - Definition: Instant events have only a single timestamp and no duration. - Use
      case: Suitable for marking significant moments or points in your code (such as
      state changes, cross-thread/async boundaries, etc.).

    ```objc {4,11}
    // Basic usage
    - (void)requestBegin {
      // ...
      [LynxTraceEvent instant:@"network" withName:@"request-begin"];
      // ...
    }

    // With custom arguments
    - (void)requestFinished {
      // ...
      [LynxTraceEvent instant:@"network" withName:@"request-finished" debugInfo:@{@"url": @"https://example.com", @"method": @"GET"}];
      // ...
    }
    ```

    ## Best Practices

    ### Begin/End Must Match on the Same Thread

    - Every `beginSection` must have a corresponding `endSection`, and both calls must occur on the same thread.
    - Do not let exceptions or early returns prevent `endSection` from being called.

    #### Bad Examples

    ```objc {6-7,13-14,19-20,23}
    // Exception causes endSection not to be called
    - (void)measureWithError:(BOOL)shouldThrow {
      [LynxTraceEvent beginSection:@"measure"];
      // ...
      @throw [NSException exceptionWithName:@"TestException" reason:@"Error occurred" userInfo:nil];
      // endSection will not be called due to exception
      [LynxTraceEvent endSection:@"measure"];
    }

    // Early return causes endSection not to be called
    - (void)measureWithFastExit:(BOOL)fastExit {
      [LynxTraceEvent beginSection:@"measure"];
      // Early return, endSection not called
      if (fastExit) return;
      // ...
      [LynxTraceEvent endSection:@"measure"];
    }

    // Cross-thread begin/end mismatch
    [LynxTraceEvent beginSection:@"background-task"];
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
      // ...
      [LynxTraceEvent endSection:@"background-task"]; // Error: not same thread
    });
    ```

    #### Good Examples

    ```objc {7-10,16-18,25-26,28}
    - (void)measureWithError:(BOOL)shouldThrow {
      @try {
        [LynxTraceEvent beginSection:@"measure"];
        // ...
        @throw [NSException exceptionWithName:@"TestException" reason:@"Error occurred" userInfo:nil];
      }
      @finally {
        // Exception safe: ensure endSection is always called
        [LynxTraceEvent endSection:@"measure"];
      }
    }

    - (void)measureWithFastExit:(BOOL)fastExit {
      [LynxTraceEvent beginSection:@"measure"];
      if (fastExit) {
        // Early return safe
        [LynxTraceEvent endSection:@"measure"];
        return;
      }
      // ...
      [LynxTraceEvent endSection:@"measure"];
    }

    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
      // Thread safe: begin/end on the same thread
      [LynxTraceEvent beginSection:@"background-task"];
      // ...
      [LynxTraceEvent endSection:@"background-task"];
    });
    ```

    ### Do Not Use Slice Events Across Async Boundaries

    - Do not use `beginSection`/`endSection` across asynchronous boundaries like timers or callbacks.
    - Slice events require start and end to be in the same synchronous context.
    - Use Instant events if you need to trace both sides of an async boundary.

    #### Bad Examples

    ```objc {2,5,9,11}
    // Timer/callback
    [LynxTraceEvent beginSection:@"async-function"];
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, time), dispatch_get_main_queue(), ^{
        // ...
        [LynxTraceEvent endSection:@"async-function"];
    });

    // Async task
    [LynxTraceEvent beginSection:@"await-task"];
    [someAsyncFunction waitUntilFinished];
    [LynxTraceEvent endSection:@"await-task"];
    ```

    #### Good Examples

    ```objc {3,5,9,11}
    // Timer/callback: use begin/end inside callback
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, time), dispatch_get_main_queue(), ^{
        [LynxTraceEvent beginSection:@"async-function"];
        // ...
        [LynxTraceEvent endSection:@"async-function"];
    });

    // Async task: use instant events
    [LynxTraceEvent instant:@"async-task" withName:@"start"];
    [someAsyncFunction waitUntilFinished];
    [LynxTraceEvent instant:@"async-task" withName:@"end"];
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    ### Slice Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png" alt="Slice Events" className="full_image" />

    - Definition: Slice events have both a start and end timestamp, representing a duration.
    - Nesting: On the same thread, slice events can be nested like a call stack.
      - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
      - Important: Child events must always end before their parent ends (i.e., B must end before A).
    - Use case: Suitable for profiling code sections where execution time matters.

    ```java {3,5,10-13,15}
    // Basic usage
    void measure() {
      TraceEvent.beginSection("render", "measure");
      // ... your code ...
      TraceEvent.endSection("render", "measure");
    }

    // With custom arguments
    void draw() {
      Map<String, String> args = new HashMap<>();
      args.put("component", "Image");
      args.put("size", "large");
      TraceEvent.beginSection("render", "draw-image", args);
      // ... your code ...
      TraceEvent.endSection("render", "draw-image");
    }
    ```

    ### Instant Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png" alt="Instant Events" className="full_image" />

    - Definition: Instant events have only a single timestamp and no duration.
    - Use case: Suitable for marking significant moments or points in your code (such as state changes, cross-thread/async boundaries, etc.).

    ```java {4,11-14}
    // Basic usage
    void requestBegin() {
      // ...
      TraceEvent.instant("network", "request-begin");
      // ...
    }

    // With custom arguments
    void requestFinished() {
      // ...
      Map<String, String> args = new HashMap<>();
      args.put("url", "https://example.com");
      args.put("method", "GET");
      TraceEvent.instant("network", "request-finished", args);
      //...
    }
    ```

    ## Best Practices

    ### Begin/End Must Match on the Same Thread

    - Every `beginSection` must have a corresponding `endSection`, and both calls must occur on the same thread.
    - Do not let exceptions or early returns prevent `endSection` from being called.

    #### Bad Examples

    ```java {5-6,11-12,17-18,21}
    public void measure() throws Exception {
      TraceEvent.beginSection("measure");
      // ...
      exceptionFunction(); // May throw exception
      // endSection not called due to exception
      TraceEvent.endSection("measure");
    }

    public void measure(boolean fastExit) {
      TraceEvent.beginSection("measure");
      // Early return causes endSection not to be called
      if (fastExit) return;
      // ...
      TraceEvent.endSection("measure");
    }

    // Cross-thread: begin/end not in the same thread
    TraceEvent.beginSection("background-task");
    new Thread(() -> {
      // ...
      TraceEvent.endSection("background-task");
    }).start();
    ```

    #### Good Examples

    ```java {6-9,15-17,24-25,27}
    public void measure() throws Exception {
      try {
        TraceEvent.beginSection("measure");
        // ...
        exceptionFunction();
      } finally {
        // Exception safe
        TraceEvent.endSection("measure");
      }
    }

    public void measure() {
      TraceEvent.beginSection("measure");
      if (fastExit) {
        // Early return safe
        TraceEvent.endSection("measure");
        return;
      }
      // ...
      TraceEvent.endSection("measure");
    }

    new Thread(() -> {
      // Thread safe: begin/end in the same thread
      TraceEvent.beginSection("background-task");
      // ...
      TraceEvent.endSection("background-task");
    }).start();
    ```

    ### Do Not Use Slice Events Across Async Boundaries

    - Do not use `beginSection`/`endSection` across asynchronous boundaries like timers or callbacks.
    - Slice events require start and end to be in the same synchronous context.
    - Use Instant events if you need to trace both sides of an async boundary.

    #### Bad Examples

    ```java {2,5,9,11}
    // Timer/callback
    TraceEvent.beginSection("async-function");
    new Handler().postDelayed(() -> {
      // ...
      TraceEvent.endSection("async-function");
    }, 3000);

    // Async task
    TraceEvent.beginSection("await-task");
    someAsyncFunction().get(); // Assume this is async wait
    TraceEvent.endSection("await-task");
    ```

    #### Good Examples

    ```java {3,5,9,11}
    // Timer/callback: use begin/end inside callback
    new Handler().postDelayed(() -> {
      TraceEvent.beginSection("async-function");
      // ...
      TraceEvent.endSection("async-function");
    }, 3000);

    // Async task: use instant events
    TraceEvent.instant("async-task", "async-task-start");
    someAsyncFunction().get();
    TraceEvent.instant("async-task", "async-task-end");
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ### Slice Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png" alt="Slice Events" className="full_image" />

    - Definition: Slice events have both a start and end timestamp, representing a duration.
    - Nesting: On the same thread, slice events can be nested like a call stack.
      - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
      - Important: Child events must always end before their parent ends (i.e., B must end before A).
    - Use case: Suitable for profiling code sections where execution time matters.

    ```javascript {3,5,10-14,16}
    // Basic usage
    function measure() {
      TraceEvent.beginSection(TraceCategory.Other, "measure");
      // ... your code ...
      TraceEvent.endSection(TraceCategory.Other, "measure");
    }

    // With custom arguments
    function draw() {
      const args: Record<string, string> = {
        "component": "Image",
        "size": "large"
      }
      TraceEvent.beginSection(TraceCategory.Other, "draw-image", args);
      // ... your code ...
      TraceEvent.endSection(TraceCategory.Other, "draw-image");
    }
    ```

    ### Instant Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png" alt="Instant Events" className="full_image" />

    - Definition: Instant events have only a single timestamp and no duration.
    - Use case: Suitable for marking significant moments or points in your code (such as state changes, cross-thread/async boundaries, etc.).

    ```javascript {4,11-15}
    // Basic usage
    function requestBegin() {
      // ...
      TraceEvent.instant(TraceCategory.Other, "request-begin")
      // ...
    }

    // With custom arguments
    function requestFinished() {
      // ...
      const args: Record<string, string> = {
        "url": "https://example.com",
        "method": "GET"
      }
      TraceEvent.instant(TraceCategory.Other, "request-finished", args);
      //...
    }
    ```

    ## Best Practices

    ### Begin/End Must Match on the Same Thread

    - Every `beginSection` must have a corresponding `endSection`, and both calls must occur on the same thread.
    - Do not let exceptions or early returns prevent `endSection` from being called.

    #### Bad Examples

    ```javascript {5-6,11-12,17-18,21}
    function measure() {
      TraceEvent.beginSection(TraceCategory.Other, 'measure');
      // ...
      throw new Error('Error occurred');
      // profileEnd not called due to exception
      TraceEvent.endSection(TraceCategory.Other, 'measure');
    }

    function measureWithFastExit(fastExit) {
      TraceEvent.beginSection(TraceCategory.Other, 'measure');
      // Early return causes profileEnd not to be called
      if (fastExit) return;
      // ...
      TraceEvent.endSection(TraceCategory.Other, 'measure');
    }

    // Cross-async/thread begin/end mismatch
    TraceEvent.beginSection(TraceCategory.Other, 'background-task');
    setTimeout(() => {
      // ...
      TraceEvent.endSection(TraceCategory.Other, 'background-task');
    }, 1000);
    ```

    #### Good Examples

    ```javascript {6-9,15-17,24-25,27}
    function measure(shouldThrow) {
      try {
        TraceEvent.beginSection(TraceCategory.Other, 'measure');
        // ...
        throw new Error('Error occurred');
      } finally {
        // Exception safe: ensure profileEnd is always called
        TraceEvent.endSection(TraceCategory.Other, 'measure');
      }
    }

    function measureWithFastExit(fastExit) {
      TraceEvent.beginSection(TraceCategory.Other, 'measure');
      if (fastExit) {
        // Early return safe
        TraceEvent.endSection(TraceCategory.Other, 'measure');
        return;
      }
      // ...
      TraceEvent.endSection(TraceCategory.Other, 'measure');
    }

    setTimeout(() => {
      // Thread safe: begin/end in the same execution context
      TraceEvent.beginSection(TraceCategory.Other, 'background-task');
      // ...
      TraceEvent.endSection(TraceCategory.Other, 'background-task');
    }, 0);
    ```

    ### Do Not Use Slice Events Across Async Boundaries

    - Do not use `beginSection`/`endSection` across asynchronous boundaries such as timers, callbacks, or `await`/`Promise`.
    - Slice events require start and end to be in the same synchronous context.
    - Use Instant events if you need to trace both sides of an async boundary.

    #### Incorrect Examples

    ```javascript {2,5,9,11}
    // Timer/callback
    TraceEvent.beginSection(TraceCategory.Other, 'async function');
    setTimeout(() => {
      // ...
      TraceEvent.endSection(TraceCategory.Other, 'async function');
    }, 3000);

    // await/promise
    TraceEvent.beginSection(TraceCategory.Other, 'await-task');
    await someAsyncFunc();
    TraceEvent.endSection(TraceCategory.Other, 'await-task');
    ```

    #### Correct Examples

    ```javascript {3,5,9,11}
    // Timer/callback: use begin/end inside the callback
    setTimeout(() => {
      TraceEvent.beginSection(TraceCategory.Other, 'async function');
      // ...
      TraceEvent.endSection(TraceCategory.Other, 'async function');
    }, 3000);

    // await/promise: use instant trace events
    TraceEvent.instant(TraceCategory.Other, 'await-task:begin');
    await someAsyncFunc();
    TraceEvent.instant(TraceCategory.Other, 'await-task:end');
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="reactlynx">
    ### Slice Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png" alt="Slice Events" className="full_image" />

    - Definition: Slice events have both a start and end timestamp, representing a duration.
    - Nesting: On the same thread, slice events can be nested like a call stack.
      - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
      - Important: Child events must always end before their parent ends (i.e., B must end before A).
    - Use case: Suitable for profiling code sections where execution time matters.

    ```javascript {3,5,10-12,14}
    // Basic usage
    function handleClick() {
      lynx.performance.profileStart('handle-click');
      // ... your code ...
      lynx.performance.profileEnd();
    }

    // With custom arguments
    useEffect(() => {
      lynx.performance.profileStart('useEffect', {
        args: { count },
      });
      // ... your code ...
      lynx.performance.profileEnd();
    }, [count]);
    ```

    ### Instant Events

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png" alt="Instant Events" className="full_image" />

    - Definition: Instant events have only a single timestamp and no duration.
    - Use case: Suitable for marking significant moments or points in your code (such as state changes, cross-thread/async boundaries, etc.).

    ```javascript {3,6-8}
    function fetchData() {
      // Basic usage
      lynx.performance.profileMark('fetch-data-begin');
      fetch(url).then((res) => {
        // With custom arguments
        lynx.performance.profileMark('fetch-data-end', {
          args: { url: 'https://example.com', method: 'GET' },
        });
      });
    }
    ```

    #### Flow Events

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

    - Description: Flows are used to link two (or more) logically related events (Slice or Instant) that may occur on different threads or at different times.
    - Visualization: In the Trace UI, flows are displayed as arrows connecting related events. When you select one event, the arrow highlights its related events.
    - Use case: Flows are especially useful for tracking the lifecycle of asynchronous tasks, request/response pairs, or any operation spanning multiple phases or contexts.

    ```javascript {1-2,7}
    const flowId = lynx.performance.profileFlowId();
    lynx.performance.profileMark('user-action-begin', { flowId });

    // ...later, in an async callback
    setTimeout(() => {
      // ...
      lynx.performance.profileMark('user-action-end', { flowId });
    }, 1000);
    ```

    ## Best Practices

    ### Begin/End Must Match on the Same Thread

    - Every `profileStart` must have a corresponding `profileEnd`, and both calls must occur on the same thread.
    - Do not let exceptions or early returns prevent `profileEnd` from being called.

    #### Bad Examples

    ```javascript {5-6,11-12,17-18,21}
    function measure() {
      lynx.performance.profileStart('measure');
      // ...
      throw new Error('Error occurred');
      // profileEnd not called due to exception
      lynx.performance.profileEnd();
    }

    function measureWithFastExit(fastExit) {
      lynx.performance.profileStart('measure');
      // Early return causes profileEnd not to be called
      if (fastExit) return;
      // ...
      lynx.performance.profileEnd();
    }

    // Cross-async/thread begin/end mismatch
    lynx.performance.profileStart('background-task');
    setTimeout(() => {
      // ...
      lynx.performance.profileEnd();
    }, 1000);
    ```

    #### Good Examples

    ```javascript {6-9,15-17,24-25,27}
    function measure(shouldThrow) {
      try {
        lynx.performance.profileStart('measure');
        // ...
        throw new Error('Error occurred');
      } finally {
        // Exception safe: ensure profileEnd is always called
        lynx.performance.profileEnd();
      }
    }

    function measureWithFastExit(fastExit) {
      lynx.performance.profileStart('measure');
      if (fastExit) {
        // Early return safe
        lynx.performance.profileEnd();
        return;
      }
      // ...
      lynx.performance.profileEnd();
    }

    setTimeout(() => {
      // Thread safe: begin/end in the same execution context
      lynx.performance.profileStart('background-task');
      // ...
      lynx.performance.profileEnd();
    }, 0);
    ```

    ### Do Not Use Slice Events Across Async Boundaries

    - Do not use `profileStart`/`profileEnd` across asynchronous boundaries such as timers, callbacks, or `await`/`Promise`.
    - Slice events require start and end to be in the same synchronous context.
    - Use Instant events if you need to trace both sides of an async boundary.

    #### Incorrect Examples

    ```javascript {2,5,9,11}
    // Timer/callback
    lynx.performance.profileStart('async function');
    setTimeout(() => {
      // ...
      lynx.performance.profileEnd();
    }, 3000);

    // await/promise
    lynx.performance.profileStart('await-task');
    await someAsyncFunc();
    lynx.performance.profileEnd();
    ```

    #### Correct Examples

    ```javascript {3,5,9,11}
    // Timer/callback: use begin/end inside the callback
    setTimeout(() => {
      lynx.performance.profileStart('async function');
      // ...
      lynx.performance.profileEnd();
    }, 3000);

    // await/promise: use instant trace events
    lynx.performance.profileMark('async-task:start');
    await someAsyncFunc();
    lynx.performance.profileMark('async-task:end');
    ```
  </PlatformTabs.Tab>
</PlatformTabs>



---
url: /guide/performance/analysis-performance/trace-track.md
---

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

# Track Overview

## What is a Track

In the Trace UI, a Track is the basic unit that displays Trace data. Each Track represents a type of events or data stream, such as thread activity, CPU frequency, memory changes, and key timing markers. Tracks let developers clearly see the occurrence order, duration, and distribution across threads on a timeline, enabling analysis of application behavior and performance bottlenecks.
A Track is shown as a horizontal bar in the Trace UI, with its name displayed on the left.

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

## Common Tracks

### Process Track

The Process Track is typically named using the process name and process id (iOS and macOS Traces use `Process {pid}`). In Lynx Trace, there is usually only one Process Track, serving as the top-level container for all other Tracks.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/process-track.png" alt="Process Track" className="full_image" />

### Thread Track

Thread Tracks are typically named using the thread name and thread id. Lynx Trace includes multiple thread Tracks such as the [UI thread](/guide/spec.md#ui-thread), [Engine thread](/guide/spec.md#engine-thread-historically-known-as-tasm-thread), and [background thread](/guide/spec.md#background-scripting-thread-historically-known-as-js-thread). Below are common Thread Tracks that help developers see the order, duration, and thread distribution of events to analyze behavior and bottlenecks.

#### UI Thread Track

The UI Thread Track shows all events and tasks on the application’s UI thread, such as page rendering, UI operations, and the main loop. Analyzing the UI Thread Track helps locate performance issues like UI stutter and render blocking. In Lynx Trace, a process contains a single UI Thread Track.

By default, the top-most Thread Track is the UI Thread Track.

- On Android and Harmony, the UI Thread Track is named `process-name pid(main thread)`.
- On iOS and macOS, the Thread Track with the smallest thread id is the UI Thread Track.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ui-thread-track.png" alt="UI Thread Track" className="full_image" />

#### Background Thread Track

The Background Thread Track shows [BTS](/guide/spec.md#background-thread-script-or-bts) execution. Use this Track to analyze BTS scheduling, execution, and duration.

:::info
For historical reasons, the background thread is named Lynx\_JS.
:::

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/background-thread-track-trace.png" alt="Background Thread Track" className="full_image" />

#### AsyncCreateView Track

The AsyncCreateView Track records the process of creating UI asynchronously and is suitable for analyzing asynchronous platform UI creation.

<img src="https://tosv.byted.org/obj/lynx-trace/async-create-view-thread-track.png" alt="AsyncCreateView Track" className="full_image" />

#### Event Report Track

The Event Report Track shows Lynx’s internal event reporting process, helping locate issues like whether an event was reported.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/event-report-thread-track.png" alt="Event Report Track" className="full_image" />

### Performance Issue Track

The Performance Issue Track is used to mark performance anomalies and bottlenecks. Developers can quickly locate hot spots and abnormal behavior via this Track.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/performance-issue-track.png" alt="Timing Track" className="full_image" />

### Timing Track

The Timing Track shows key timestamps (such as first screen render done and actual first meaningful paint), helping developers locate key milestones.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing-track.png" alt="Timing Track" className="full_image" />

### NativeModule Track

The [NativeModule](/guide/use-native-modules.md#原生模块) Track shows the NativeModule invocation process, including JS–Native communication and data conversion. Use it to analyze native module flows and performance bottlenecks.

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

### CPU Frequency Track

The CPU Frequency Track displays changes in CPU frequency over time as a line chart, helping developers analyze CPU resource usage under high load.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/cpu-frequency-track.png" alt="CPU Frequency Track" className="full_image" />

### Memory Track

The Memory Track shows Lynx page memory usage changes over time, with each Memory Track representing one Lynx page. Use it to analyze memory leaks, peaks, and abnormal growth.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/memory-track-latest.png" alt="Memory Track" className="full_image" />

## Common Track operations

### Pin Track

Pin Track fixes a Track at the top of the Trace view for easier comparison and continuous focus on key threads or events.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/pin-to-top-track.png" alt="Pin To Top" className="full_image" />

### Delete Track

Delete Track lets developers temporarily hide Tracks that are not of interest, simplifying the UI and leaving only the Tracks needed for analysis to improve efficiency. Deleted Tracks reappear after refreshing the Trace page.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/delete-track.png" alt="Delete Track" className="full_image" />

## More resources

For a more detailed guide on Trace Tracks and advanced features, see the official Perfetto documentation: [perfetto-ui](https://perfetto.dev/docs/visualization/perfetto-ui)



---
url: /guide/performance/monitor-performance.md
---

# Performance Monitoring Overview

This overview helps you quickly build a mental model and understand common workflows for performance monitoring. It explains how the [Performance API](/guide/performance/monitor-performance/performance-api.md) and [Timing Flag](/guide/performance/monitor-performance/timing-flag.md) work together to create a closed loop from marking to analysis: `Mark` → `Collect` → `Report` → `Analyze`.

## Mental Model and Closed-Loop Workflow

The goal of monitoring is to ensure that critical moments in your page's lifecycle can be accurately recorded, reported, and analyzed, allowing you to quickly trace issues back to the source code or specific UI locations. Centered around the Lynx rendering pipeline and standardized events, we recommend the following closed-loop workflow:

- **Mark**: Use a Timing Flag (`__lynx_timing_flag`) on critical UI nodes or key data updates to define the rendering pipelines you need to monitor. The special flag `__lynx_timing_actual_fmp` can additionally generate the ActualFMP metric. For details, see [Marking Rendering Pipelines](/guide/performance/monitor-performance/timing-flag.md).
- **Collect**: Register a `PerformanceObserver` as early as possible on the front end (e.g., to listen for `metric.fcp`, `pipeline`, etc.), or consume events via asynchronous callbacks on the client side. For details, see [Collecting Performance Events](/guide/performance/monitor-performance/performance-api.md).
- **Report**: Report key metrics and events to your data platform using consistent naming and fields.
- **Analyze**: Analyze production data, using `PipelineEntry.identifier` (the Timing Flag) and event timelines to trace problems back to the corresponding modules or data flows for debugging and review.

Recommended minimum set of tracking points (for a basic production setup):

- **metric**: `fcp` (required), `actual_fmp` (when you need to measure the "first meaningful data paint")
- **pipeline**: `loadBundle` (for the initial screen rendering), and the pipelines associated with your critical Timing Flags.

## Feature Positioning

### [Performance API](/guide/performance/monitor-performance/performance-api.md)

- **Positioning**: A standardized performance interface covering four event types: `init`, `metric`, `pipeline`, and `resource`.
- **Triggering and Retrieval**: `PerformanceEntry` objects are generated by the Lynx Engine. The front end subscribes to them via `PerformanceObserver.observe([...])`, and the client receives them through the `onPerformanceEvent(entry)` callback on an asynchronous thread.
- **Typical Uses**:
  - Obtaining standard metrics for initial screen rendering and key updates (FCP, ActualFMP).
  - Combining multiple events to build custom business metrics (e.g., the waiting time from the end of the initial screen rendering to the first important data update).

### [Marking Lynx Pipeline](/guide/performance/monitor-performance/timing-flag.md)

- **Positioning**: A unique identifier used to mark a rendering pipeline for monitoring. It triggers the generation of a `PipelineEntry` and can also trigger a `MetricActualFmpEntry`.
- **Usage**:
  - The recommended method is to set the `__lynx_timing_flag` attribute on a UI element.
  - Setting the value to `__lynx_timing_actual_fmp` additionally generates an ActualFMP metric event.
- **Behavior and Limitations**:
  - The same Timing Flag is only effective the first time it is encountered (repeated markings will not trigger the callback again).
  - It is ineffective on tags that do not have a UI node, such as `<inline text/>`, `<block/>`, and `<template/>`.

## Common Workflows

- **Mark critical stages** → Get key moments via `PipelineEntry`/`ActualFMP` → Combine with `LoadBundleEntry`/`FCP` to establish a baseline for initial rendering and updates → **Report** → Filter high-latency samples by different dimensions → Trace back to the component/data flow corresponding to the mark to identify the cause.
- **Lazy-loaded component performance** → Set a Timing Flag on important nodes and listen for the corresponding `PipelineEntry` → Combine with the page's `loadBundle` event to create an end-to-end performance profile → Optimize the resource loading and layout stages separately.



---
url: /guide/performance/monitor-performance/performance-api.md
---

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


# Performance API

## Concepts and usage

Measuring and analyzing performance metrics is critical to ensure the speed and user experience of Lynx applications. Similar to the [Web standard](https://developer.mozilla.org/en-US/docs/Web/API/Performance), Lynx provides the **Performance API** as a standardized interface to measure Lynx app performance, helping developers monitor comprehensive metrics from initialization through rendering completion.

<center>
  <img width="60%" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/performance-api-v4.png" />
</center>

### Performance entry types

The core of the Performance API is the **[`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md)** object, which is the fundamental data structure describing a performance event. Each PerformanceEntry has the following basic properties:

- `entryType`: The type of performance event (e.g., `init`, `metric`, `pipeline`, `resource`)
- `name`: The specific name of the performance event
- Other type-specific properties and timestamps

Based on the `entryType` property, the Performance API supports four main categories of performance events:

- **Initialization events (`init`)**

  - [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md): Container initialization performance event
  - [`InitLynxviewEntry`](/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md): LynxView initialization performance event
  - [`InitBackgroundRuntimeEntry`](/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md): Background runtime initialization performance event

- **Metric events (`metric`)**

  - [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md): FCP (First Contentful Paint)
  - [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md): ActualFMP (Actual First Meaningful Paint)

- **Rendering pipeline events (`pipeline`)**

  - [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md): Performance event for [flagged rendering pipelines](/guide/performance/monitor-performance/timing-flag.md)
  - [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md): Performance event for [TemplateBundle](/api/lynx-native-api/template-bundle.md) loading and first-screen rendering
  - [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md): Performance event for reloading [TemplateBundle](/api/lynx-native-api/template-bundle.md)

- **Resource loading events (`resource`)**
  - [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md): Performance event for lazy-loaded [TemplateBundle](/api/lynx-native-api/template-bundle.md)

### Getting performance data

#### Front-end developers

To consume performance events, the Performance API provides **PerformanceObserver**, which notifies you when the **Lynx Engine** produces performance events (`PerformanceEntry`).

The PerformanceObserver object offers the `observe` method to start observing and the `disconnect` method to stop. With them, you can observe by `entryType` (all entries of a type) or `entryType.name` (a specific kind of entry).

To prevent missing events due to late registration, register observations as early as possible.

- **Component dependencies**

  - `@lynx-js/react` >= 0.107.0

- **Registration timing**
  - Class components: register in the **constructor**
  - Function components: register in **useMemo**

The following example shows how to create a `PerformanceObserver` and observe [`metric.fcp`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`pipeline`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) events.

**This is an example below:  performance-api**

**Entry:** `src/simple-observe`
```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function SimpleObserveExample(this: any) {
  const [receivedEntries, setReceivedEntries] = useState<Set<string>>(new Set<string>());

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fcp") {
        entryType = "MetricFcpEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["metric.fcp", "pipeline"]);
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver</text>
      </view>
      <view className="card">
        <text className="section-title">Received PerformanceEntry:</text>
        <view className="entries-container">
          {Array.from(receivedEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<SimpleObserveExample />);

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

```



#### Client developers

On the client side, performance events sent by the Performance API are delivered via the `onPerformanceEvent(PerformanceEntry entry)` callback on LynxViewClient on an **asynchronous thread**. It is therefore not recommended to perform any UI-related operations inside this callback.

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="android">
    ```java
    import com.lynx.tasm.LynxViewClientV2;
    import com.lynx.tasm.performance.performanceobserver.PerformanceEntry;
    import com.lynx.tasm.performance.performanceobserver.MetricFcpEntry;

    public class CustomLynxViewClient extends LynxViewClientV2 {
      @Override
      public void onPerformanceEvent(@NonNull PerformanceEntry entry) {
        // If you need to consume raw data directly, convert to HashMap
        Log.d(entry.toHashMap());
        // If you need to consume a specific type, cast and use inner fields
        if (entry.entryType.equals("metric") && entry.name.equals("fcp")) {
          MetricFcpEntry fcpEntry = (MetricFcpEntry) entry;
          Log.d("lynxFcp is %s", fcpEntry.lynxFcp.duration);
        }
      }
    }
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="ios">
    ```objc
    #import "LynxViewClient.h"
    #import "LynxMetricFcpEntry.h"

    @interface CustomLynxViewClient : NSObject <LynxViewLifecycleV2>
    @end
    @implementation

    - (void)onPerformanceEvent:(LynxPerformanceEntry*)entry {
      // If you need to consume raw data directly, convert to NSDictionary*
      NSLog(entry.toDictionary);
      // If you need to consume a specific type, cast and use inner fields
      if ([entry.entryType isEqual: @"metric"] && [entry.name isEqual: @"fcp"]) {
        MetricFcpEntry* fcpEntry = (LynxMetricFcpEntry *) entry;
        NSLog(@"lynxFcp is %@", fcpEntry.lynxFcp.duration);
      }
    }
    @end

    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ```typescript
    import { LynxViewClient, PerformanceEntry, MetricFcpEntry } from '@lynx/lynx';

    export class CustomLynxViewClient extends LynxViewClient {
      public onPerformanceEvent(entry: PerformanceEntry): void {
        // If you need to consume raw data directly, convert to Record
        Log.d(entry.Record);
        // If you need to consume a specific type, cast and use inner fields
        if (entry.entryType == 'metric' && entry.name == 'fcp') {
          let fcpEntry: MetricFcpEntry = entry as MetricFcpEntry;
          Log.d('lynxFcp is %s', fcpEntry.lynxFcp.duration);
        }
      }
    }
    ```
  </PlatformTabs.Tab>
</PlatformTabs>

## [Capture specific rendering pipelines](/guide/performance/monitor-performance/timing-flag.md)

A [rendering pipeline](/guide/spec.md#lynx-pipeline) is the complete process from triggering the rendering to displaying it on the screen. If you care about the rendering performance of certain key components, set the component’s `__lynx_timing_flag` property to mark the pipeline it belongs to and monitor its performance.

When the flagged rendering pipeline completes and the screen is refreshed, a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) event is generated. You can retrieve it via [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md).

## Build custom performance metrics

Different business goals imply different metrics to focus on. Your use of the Performance API need not be limited to built-in Lynx metrics—you can flexibly combine timestamps from different `PerformanceEntry`s at key points to construct a metric suite tailored to your application.

For example, if you want to measure the latency from the end of first-screen rendering to the first important data update, you can combine `LoadBundleEntry` and `PipelineEntry` to compute a custom metric `waitingDuration` as shown below. It helps monitor the speed of network requests, file IO, etc., and pinpoint causes of performance regressions.

![waiting duration](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/custom-metric-waitingduration.png)

**This is an example below:  performance-api**

**Entry:** `src/simple-observe`
**Bundle:** `dist/actual-fmp-entry.lynx.bundle`

```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useEffect, useMemo, useRef, useState } from "@lynx-js/react";
import type { LoadBundleEntry, PerformanceEntry, PerformanceObserver, PipelineEntry } from "@lynx-js/types";
import "../common/common.css";

export default function CreateCustomPerformanceMetricExample(this: any) {
  const [loadBundleEnd, setLoadBundleEnd] = useState<number>(0);
  const [pipelineStart, setPipelineStart] = useState<number>(0);
  const [waitingDuration, setWaitingDuration] = useState<number>(0);
  const [state, setState] = useState({
    importantElement: "Loading",
    __lynx_timing_flag: "",
  });

  const loadBundleEndRef = useRef(0);
  const observerRef = useRef<PerformanceObserver>();

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      if (entry.entryType == "pipeline" && entry.name == "loadBundle") {
        // 3. Received "pipeline.loadBundle" event.
        const LoadBundleEntry = entry as LoadBundleEntry;
        setLoadBundleEnd(LoadBundleEntry.loadBundleEnd);
      } else if (entry.entryType == "pipeline") {
        // 4. calculate waitingDuration
        const pipelineEntry = entry as PipelineEntry;
        if (pipelineEntry.identifier == "important-update") {
          setPipelineStart(pipelineEntry.pipelineStart);
          setWaitingDuration(pipelineEntry.pipelineStart - loadBundleEndRef.current);
          observer.disconnect();
        }
      }
    });
    // 2. register to listen to the "pipeline" event.
    observer.observe(["init", "pipeline"]);
    observerRef.current = observer;
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  useEffect(() => {
    loadBundleEndRef.current = loadBundleEnd;
  }, [loadBundleEnd]);

  useEffect(() => {
    const timeout = setTimeout(() => {
      setState(() => ({
        __lynx_timing_flag: "important-update",
        importantElement: "Display",
      }));
    }, 3000);

    return () => {
      clearTimeout(timeout);
    };
  });

  return (
    <view className="container">
      <text className="title">Create Your Performance Metric</text>
      <view className="card">
        <text className="entry highlight" __lynx_timing_flag={state.__lynx_timing_flag}>
          🎯 {state.importantElement} important element
        </text>
        <text className="entry">⏱️ loadBundleEnd: {loadBundleEnd} ms</text>
        <text className="entry">⏱️ updateTime: {pipelineStart} ms</text>
        <text className="entry">⏳ waitingDuration: updateTime - loadBundleEnd = {waitingDuration} ms</text>
      </view>
    </view>
  );
}

root.render(<CreateCustomPerformanceMetricExample />);

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

```



## Best practices

### 1. Register observers early

To avoid missing events due to late registration, register observations as early as possible:

- Register in the class component `constructor`, or in `useMemo` for function components

### 2. Choose an appropriate observe scope

Select the observe scope based on your needs:

```typescript
// Observe all metric events
observer.observe(['metric']);

// Observe only FCP metric events
observer.observe(['metric.fcp']);

// Observe multiple specific events
observer.observe(['metric.fcp', 'pipeline.loadBundle']);
```

### 3. Clean up promptly

When a component unmounts or observation is no longer needed, call `disconnect()` to release resources:

```typescript
useEffect(() => {
  return () => {
    if (observer) {
      observer.disconnect();
    }
  };
}, []);
```

## FAQ

### Q1: If my page uses [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md), do I still need to mark a Timing Flag?

For pages with [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md), you generally do not need to manually mark a Timing Flag. However, if you do, you will still receive a `LoadBundleEntry` with an `identifier` value equal to the TimingFlag you marked.

### Q2: My page uses [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md). How can I get the ActualFMP performance metric?

In scenarios with [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md), you generally do not need to focus on the ActualFMP performance metric; you only need to pay attention to the FCP metric. The FCP metric can be obtained directly through `MetricFcpEntry`.

### Q3: Can I get the rendering time of lazy-loaded components?

Yes. Marking Timing Flags on lazy-loaded components works the same as on the main page; you can use the Timing Flag inside the lazy-loaded component:

```typescript
export default function MyLazyBundle() {
  return (
    <view className="root">
      <text className="text", __lynx_timing_flag="dynamic_render" >Hello, This is a Lazy Bundle!</text>
    </view>
  );
}
```

```typescript
export default function app() {
  return (
    <view className="container">
      <text className="title">Hello LazyBundleEntry~</text>
      <Suspense fallback={<text className="sub-text">Loading...</text>}>
        <MyLazyBundle />
      </Suspense>
      <ScrollItem title={entryName} value={lazyBundleEntry} />
    </view>
  );
}
```

This method can be used to obtain the timestamp of the dynamic component rendering phase. For information about the time consumption of the dynamic component resource loading phase, refer to [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md).

### Q4: Are Performance API callbacks related to other Lynx lifecycles?

Performance API triggers its callbacks after all rendering pipeline timestamps are captured—i.e., after pixels are on screen—and has no strict ordering relationship with other Lynx lifecycles.

### Q5: Which is triggered faster, a setState callback or a Performance API callback?

See Q4: there is no defined ordering.

### Q6: Can Timing Flags be reused?

No. If two identical Timing Flags are injected, Performance API fires on the first one it detects and will not fire again for the second.

### Q7: What happens if the client calls ReloadTemplate, calls LoadTemplate multiple times, or the front end calls reload?

**Before Lynx 3.4**: Performance API state resets; LoadBundleEntry will be triggered again with timestamps from this template load. If front-end reloads but the page has no UI to redraw, no callback is received.

**After Lynx 3.4**: Multiple LoadTemplate calls yield multiple LoadBundleEntry events; client ReloadTemplate and front-end reload yield ReloadBundleEntry.

### Q8: Why don’t I receive the LoadBundleEntry callback?

Possible causes:

1. First-screen rendering produced no pixels, e.g., LynxView width/height is 0, LynxView is off-screen, or LynxView wasn’t added to the window.
2. The observer was registered too late; try registering earlier:
   - register in the class constructor or `useMemo`

### Q9: I used an Timing Flag—why don’t I receive PipelineEntry callbacks?

Possible causes:

1. Observer registered too late (see Q8)
2. Timing Flag is set on a Component while the `removeComponentElement` switch is enabled, making the Timing layer unable to detect the flag
3. Timing Flag is ineffective on tags with no UI nodes, such as `<inline text/>`, `<block/>`, `<template/>`
4. The same Timing Flag does not trigger multiple callbacks (see Q6)

### Q10: How do I verify that Timing Flag integration works?

You can validate via local Trace, or by registering an observer and checking whether callbacks fire.

### Q11: My ActualFMP metric is particularly large—why?

Check whether preloading is in effect; with preloading, the starting point of ActualFMP can be very early.

### Q12: Error “OnPipelineStart arg count must == 1”

To fix this, upgrade `@lynx-js/react` to version 0.107.1 or higher.



---
url: /guide/performance/monitor-performance/timing-flag.md
---

# Mark Rendering Pipelines

[Lynx Pipeline](/guide/spec.md#lynx-pipeline) defines the complete process from triggering the rendering to displaying it on the screen. If you care about rendering performance of certain key components, you can set the component’s `__lynx_timing_flag` property to mark its Lynx Pipeline and monitor its performance.

When the flagged Lynx Pipeline finishes and the screen is refreshed, a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) performance event is generated. You can obtain it via [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md).

## Usage rules

- The `__lynx_timing_flag` attribute must be a non-empty string. Empty values or invalid types will not trigger [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md) callbacks.
- When the `__lynx_timing_flag` attribute value is `__lynx_timing_actual_fmp`, an additional [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md) performance event is generated.

## Examples

1. Mark a node: set the `__lynx_timing_flag` attribute on the target component. When the node finishes rendering, the framework automatically collects performance data for its Lynx Pipeline.
2. Get data: register an observer (`PerformanceObserver`) via [`lynx.performance.createObserver()`](/api/lynx-api/lynx/lynx-performance.md#createobserver) to receive the corresponding performance data (`PipelineEntry`).


**This is an example below:  performance-api**

**Entry:** `src/pipeline-entry`
**Bundle:** `dist/pipeline-entry.lynx.bundle`

```tsx {11-21,34}
import { root, useEffect, useState } from "@lynx-js/react";
import type { PerformanceEntry, PipelineEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function PipelineEntryExample() {
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [myName, setMyName] = useState<string | undefined>(undefined);

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline" event of "myPipeline".
        const pipelineEntry = entry as PipelineEntry;
        // `PerformanceEntry.identifier` is equal to `view.__lynx_timing_flag`.
        if (pipelineEntry.identifier == "myNamePipeline") {
          setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMyName("PipelineEntry");
    }, 2000);
  }, []);

  return (
    <view className="container">
      <text className="title" __lynx_timing_flag={myName ? "myNamePipeline" : ""}>Hello {myName}~</text>
      <ScrollItem title="PipelineEntry" value={pipelineEntry} />
    </view>
  );
}

root.render(<PipelineEntryExample />);

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

```



## Notes

### 1. Multiple components set the same `__lynx_timing_flag` attribute

```ts
export default function App() {
  const [showImage, setShowImage] = useState(false);

  useEffect(() => {
    setTimeout(() => {
      setShowImage(true);
    }, 3000);
  }, []);

  return (
    <view className="container">
      <text __lynx_timing_flag="__lynx_timing_actual_fmp">Hello World</text>
      {showImage && <image __lynx_timing_flag="__lynx_timing_actual_fmp" src="xxxx.png" />}
    </view>
  );
}
```

In this case, only the Lynx Pipeline data of the first component that appears on screen will be recorded:

1. Compute `ActualFMP` once and send one [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).
2. Send one [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

If you want to record the moment when both components finish rendering, use different `__lynx_timing_flag` values.

### 2. The same component renders multiple times

```ts
export default function App(this: any) {
  return (
    <view className="container">
      {
         // needShow: true -> false -> true
         data.needShow ? <text __lynx_timing_flag="__lynx_timing_actual_fmp">{data.msg}</text> : null
      }
    </view>
  );
}
```

In this scenario, only the Lynx Pipeline data for the component’s first appearance is recorded:

1. Compute `ActualFMP` once and send one [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).
2. Send one [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

If you need to measure each render individually, implement as follows:

```ts
let isFirst = true;
export default function App(this: any) {
  return (
    <view className="container">
      {
         // needShow: true -> false -> true
         data.needShow ? <text __lynx_timing_flag={"__lynx_timing_actual_fmp" + (isFirst ? "" : +data.id)}>{data.msg}</text> : null
      }
    </view>
  );
}
```

## Compatibility


**Error:** No compatibility data found for `lynx-api.performance-api.timing-flag`


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



---
url: /guide/scripting-runtime/main-thread-runtime.md
---

# Main Thread Runtime

## [PrimJS](https://github.com/lynx-family/primjs)

The main thread uses PrimJS as the runtime engine. PrimJS is a lightweight, high-performance JavaScript engine designed specifically for Lynx. PrimJS is built on top of [QuickJS](https://bellard.org/quickjs/) and offers a much better performance and development experience than QuickJS.

Meanwhile, PrimJS provides a high-performance FFI capability, which can encapsulate the Lynx object as a JS object and return it to the FFI caller at low cost, which has obvious performance advantage over the traditional FFI. However, this type of JS object is not an Object Model, Lynx engine can not bind setter getter methods to this object, it can only provide FFI to pass it as a parameter to realize similar functions.

## [Element PAPI](/api/engine/element-api.md) Bindings

In order to achieve high performance, the Element PAPI provided in the main thread runtime is based on the above approach. Since ReactLynx developers don't need to manipulate Element directly in most scenarios, this limitation of high-performance FFI doesn't degrade the experience.

If developers need to operate Element directly, we provide the [main-thread-element](/api/lynx-api/main-thread/main-thread-element.md) based on the Element PAPI to improve the development experience.

## [Lynx API](/api/lynx-api/main-thread.md) Bindings

Because of the special nature of the main thread, we only provide Lynx APIs in the main thread that do not affect rendering, which are a subset of the background thread APIs.

## Runtime Script Format

For performance optimization, the main thread scripts use the bytecode format compiled by PrimJS. This format avoids the parsing of scripts at runtime, and the bytecode format can be loaded about four times faster than normal text format scripts.



---
url: /guide/spec.md
---

{/* # Living Specification */}


<HtmlViewer path="/living-spec/index.html" />



---
url: /guide/start/integrate-lynx-dev-version.md
---

# Integrate Lynx development version

During Lynx page development, you can use the Trace and Lynx Recorder tools for debugging, analysis, and locate issues.
To avoid impacting production performance, the official release version of Lynx does not include Trace and Recorder features.
For developer convenience, Lynx also provides a development version (with a `-dev` suffix in the version number). Starting from `release/3.4`, Lynx provides a dev version for each release version (the dev version uses the same release version number with a `-dev` suffix). You can integrate the Lynx development version by following the steps below.

:::info

You can find the development version corresponding to your release version at [github](https://github.com/lynx-family/lynx/tags).

:::

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



---
url: /guide/start/integrate-lynx-devtool-advanced.md
---

# Advanced DevTool Configurations

## Integrate DevTool Switch Page

We provide a switch page that helps you quickly view or set DevTool. If you want, you can integrate it into your app as well.

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


---
url: /guide/start/integrate-lynx-devtool.md
---

# Integrating Lynx DevTool

When encountering issues during Lynx page development, you can use [DevTool](/guide/devtool/panels.md) for debugging.
However, you need to follow these steps to integrate DevTool first.

:::info
It is recommended to integrate DevTool in non-production environments to keep your production builds lightweight.

- **Package size**: DevTool will increase the package size.
- **Runtime**: Related modules are lazy loaded when enabled, which will increase memory overhead, and some features may affect the loading performance.

All code examples in this documentation can be found in the [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/main).
:::

<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

      DevTool Service provides some preset values to control default behaviors. You can configure them as needed.

      In the next chapter, we will introduce these preset values in detail.

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

            // set DevTool preset values
            LynxDevToolService.getINSTANCE().setLynxDebugPresetValue(true);
            LynxDevToolService.getINSTANCE().setLogBoxPresetValue(true);
            LynxDevToolService.getINSTANCE().setLoadJsBridge(true);
          }

          ```
        </Tab>

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

            // set DevTool preset values
            LynxDevToolService.INSTANCE.setLynxDebugPresetValue(true)
            LynxDevToolService.INSTANCE.setLogBoxPresetValue(true)
            LynxDevToolService.INSTANCE.setLoadJsBridge(true)
          }
          ```
        </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 set the `LoadJsBridge` preset value to `true`.
        * 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-8}
          private void initLynxEnv() {
            LynxEnv.inst().init(this, null, null, null);
            // Enable Lynx Debug
            LynxEnv.inst().enableLynxDebug(true);
            // Enable Lynx DevTool
            LynxEnv.inst().enableDevtool(true);
            // Enable Lynx LogBox
            LynxEnv.inst().enableLogBox(true);
          }

          ```
        </Tab>

        <Tab label="Kotlin">
          ```kotlin title=YourApplication.kt {3-8}
          private fun initLynxEnv() {
            LynxEnv.inst().init(this, null, null, null)
            // Enable Lynx Debug
            LynxEnv.inst().enableLynxDebug(true)
            // Enable Lynx DevTool
            LynxEnv.inst().enableDevtool(true)
            // Enable Lynx LogBox
            LynxEnv.inst().enableLogBox(true)
          }
          ```
        </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>



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



---
url: /guide/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>



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



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



---
url: /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` | Web: `dist/Swiper.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/product_detail_assets.zip) to use in your projects.

## Direct Node Manipulation

Here's a product detail page example that includes a swiper and some product details. The `<Swiper>` accepts images and displays them in a row. Currently, it can't scroll - let's make it interactive.

**This is an example below:  swiper**

**Entry:** `src/SwiperEmpty, src/utils/pics.ts`
**Bundle:** `dist/SwiperEmpty.lynx.bundle` | Web: `dist/SwiperEmpty.web.bundle`

```tsx {10}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} />
    </Page>
  );
}

root.render(<App />);

```



To achieve this, we need to complete two tasks:

1. Listen to touch events
2. Update scroll position

### Listen to Touch Events

Let's start by listening to touch events to calculate the current scroll progress.

When a touch starts, we record the initial touch coordinates. This allows us to calculate the distance moved (represented by `delta`) when the finger moves.

```tsx title="index.tsx" "{4-6,8-10}"
function Swiper() {
  const touchStartXRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
  }

  return (
    <view
      class="swiper-container"
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
    >
      {/* ... */}
    </view>
  );
}
```

Next, we use `currentOffsetRef` to track the swiper component's offset, adding it to `delta` to get the final offset.

```tsx title="index.tsx" "{13}"
function Swiper() {
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
  }
}
```

### Updating Scroll Position

Once we get the offset, we can update the scroll position. Add an `updateSwiperOffset` function and call it when the finger moves.

```tsx title="index.tsx" "{9}"
function Swiper() {
  function updateSwiperOffset(offset: number) {
    // Update scroll position
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
    updateSwiperOffset(offset);
  }
}
```

Next, we use [Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md) to update the `transform` property, thereby updating the scroll position.

```tsx title="index.tsx" "{5-9,14}"
function Swiper() {
  const containerRef = useRef<NodesRef>(null);

  function updateSwiperOffset(offset: number) {
    containerRef.current
      ?.setNativeProps({
        style: {
          transform: `translateX(${offset}px)`,
        },
      })
      .exec();
  }

  return <view ref={containerRef}></view>;
}
```

**This is an example below:  swiper**

**Entry:** `src/UpdateOffset, src/utils/pics.ts`
**Bundle:** `dist/UpdateOffset.lynx.bundle` | Web: `dist/UpdateOffset.web.bundle`

```tsx
import "./styles.scss";
import { useRef } from "@lynx-js/react";
import type { NodesRef, TouchEvent } from "@lynx-js/types";
import { SwiperItem } from "./SwiperItem";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const containerRef = useRef<NodesRef>(null);
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function updateSwiperOffset(offset: number) {
    currentOffsetRef.current = offset;
    containerRef.current?.setNativeProps({
      transform: `translateX(${offset}px)`,
    }).exec();
  }

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;

    updateSwiperOffset(offset);
  }

  function handleTouchEnd(e: TouchEvent) {
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



Now the `<Swiper>` component can scroll with finger movements!

::: details Why not use state to update progress?
You might think of using `state` to update the progress, like this:

```tsx title="Swiper.tsx"
function Swiper() {
  const [offset, setOffset] = useState(0);

  return (
    <view style={{ transform: `translateX(${offset}px)` }}>{/* ... */}</view>
  );
}
```

However, in scenarios requiring frequent updates, this approach would cause constant component re-rendering, affecting performance. A better approach is to directly manipulate nodes, as shown in the example.

You can refer to [Direct Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to learn more.
:::

### Simplifying Code with Hooks

The `<Swiper>` component's code is getting complex. We can use hooks to encapsulate the logic into two parts, simplifying the component code and improving maintainability:

1. Encapsulate the [touch event listening](#listening-to-touch-events) code into `useOffset`, centralizing all scroll-related logic in this hook
2. Encapsulate the [scroll position update](#updating-scroll-position) code into `useUpdateSwiperStyle`, centralizing all `<Swiper>` component style update logic in this hook

```tsx title="Swiper.tsx"
function Swiper() {
  const { updateSwiperStyle, swiperContainerRef } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view
      class="swiper-container"
      ref={swiperContainerRef}
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
      bindtouchend={handleTouchEnd}
    >
      {/* ... */}
    </view>
  );
}
```

Finally, the code is more concise.

**This is an example below:  swiper**

**Entry:** `src/SwiperHooks, src/utils/pics.ts`
**Bundle:** `dist/SwiperHooks.lynx.bundle` | Web: `dist/SwiperHooks.web.bundle`

```tsx {13-16}
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



## Use Main Thread Script to Reduce Latency

You may have noticed that sometimes the scrolling doesn't feel smooth. This is because touch events occur in the **main thread**, while event listener code runs in the **background thread**, causing delayed touch event responses. This phenomenon is particularly noticeable on low-end devices.

We can use [Main Thread Script](/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



To achieve that, we need to migrate frequently triggered code to main thread script, including:

1. Event listener code
2. Node position update code

Let's modify both `useOffset` and `useUpdateSwiperStyle`.

### `useOffset`

Add the `main thread` identifier to `handleTouchStart` and `handleTouchMove` to convert them into **main thread functions**.

```tsx title="useOffset.ts"
function useOffset() {
  const touchStartXRef = useMainThreadRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    'main thread'
    ...
  }

  function handleTouchMove(e: TouchEvent) {
    'main thread'
    ...
  }
}
```

Convert `bindtouchstart` and `bindtouchmove` to `main-thread:bindtouchstart` and `main-thread:bindtouchmove` to listen to events in main thread script.

```tsx title="index.tsx"
<view
  main-thread:bindtouchstart={handleTouchStart}
  main-thread:bindtouchmove={handleTouchMove}
>
  {/* ... */}
</view>
```

### `useUpdateSwiperStyle`

Convert `useRef` to `useMainThreadRef`.

```tsx title="useUpdateSwiperStyle.ts" "{2}"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
   'main thread'
    ...
  }

  return {
    swiperContainerRef,
  }
}
```

Pass `swiperContainerRef` to `<view>` through the `main-thread:ref` attribute to access the node in the main thread.

```tsx title="index.tsx"
<view main-thread:ref={swiperContainerRef}>{/* ... */}</view>
```

The main thread node provides many capabilities, as shown in [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md). Here we call the `setStyleProperties` method to modify the `transform` property, updating the `<Swiper>` component's position.

```tsx title="useUpdateSwiperStyle.ts"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
    'main thread';
    swiperContainerRef.current?.setStyleProperties({
      transform: `translateX(${offset}px)`,
    });
  }
}
```

With this, we've completed the main thread script conversion. Now high-frequency functions run in the main thread, making the interaction smoother.

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



::: details Use Main Thread Script Sparingly
Only use main thread script when encountering response delay issues with frequently triggered events!

- Introducing main thread script increases code complexity because main thread script and background thread script run in isolated environments and need "special bridges" to communicate.

- Main thread script run high-frequency code in the main thread, increasing its burden. Overuse may cause main thread lag.

:::

## Communication Between Main Thread and Background Thread

Here's a progress indicator example that shows which page you're on when scrolling.

Currently, it only has styling but lacks progress update logic. We'll use this example to demonstrate how to enable communication between main thread and background thread:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorEmpty, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorEmpty.lynx.bundle` | Web: `dist/MTSIndicatorEmpty.web.bundle`

```tsx {33}
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



### Main Thread Calling Background Thread

The core of the progress indicator is the `<Indicator>` component, which accepts a `current` prop indicating the current page.

```tsx title="Swiper.tsx" "{7}"
function Swiper() {
  const [current, setCurrent] = useState(0);

  return (
    <view>
      {/* ... */}
      <Indicator current={current} />
    </view>
  );
}
```

Now we just need to update `current` when scrolling.

We add an `onIndexChange` callback to `useOffset` to update `current` during scrolling.

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      onIndexUpdate(index);
    }
  }
}
```

And pass `setCurrent` as the `onIndexUpdate` callback to `useOffset`.

```tsx title="Swiper.tsx" "{4}"
const [current, setCurrent] = useState(0);

const { handleTouchMove } = useOffset({
  onIndexUpdate: setCurrent,
});
```

This way, when scrolling past a page, `useOffset` will call `onIndexUpdate` to update `current`, thereby updating the progress indicator.

But wait, why is there an error?!

![Error](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/tutorial/Swiper/MTSIndicatorWrong.png)

:::info Main Thread and Background Thread Functions Need Special APIs to Call Each Other
Main thread script and background thread script run in separate runtimes. Functions in one runtime cannot directly call functions in another runtime. They need "special bridges" to communicate:

- From background to main thread: Use [`runOnMainThread`](/api/react/Function.runOnMainThread.md)
- From main thread to background: Use [`runOnBackground`](/api/react/Function.runOnBackground.md)

:::

`onIndexUpdate` is a background thread function. When called in a main thread function, we need to use `runOnBackground`

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }
}
```

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorCurrent, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorCurrent.lynx.bundle` | Web: `dist/MTSIndicatorCurrent.web.bundle`

```tsx
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
    onIndexUpdate: setCurrent,
    itemWidth,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



Now the progress indicator updates automatically as you scroll!

### Background Thread Calling Main Thread

A useful progress indicator should also support clicking to jump to the corresponding page. Let's add click-to-jump functionality to the `<Indicator>` component.

Add an `updateIndex` method in `useOffset` that uses `runOnMainThread` to call `updateOffset` to update the component position.

```tsx title="useOffset.ts" "{4}"
function useOffset({ itemWidth, onIndexUpdate }) {
  function updateIndex(index: number) {
    const offset = index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  return {
    updateIndex,
  };
}
```

Here's the complete code:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicator, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicator.lynx.bundle` | Web: `dist/MTSIndicator.web.bundle`

```ts
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function updateOffset(offset: number) {
    "main thread";
    currentOffsetRef.current = offset;
    onOffsetUpdate(offset);
    const index = Math.round(-offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



Great! Now the progress indicator supports click-to-jump functionality.

## Values Across Main Thread and Background Thread Script

In the following example, we've added a snap effect animation to the `<Swiper>` component. Currently, the snap effect animation isn't ideal, we can add some props to customize it.

**This is an example below:  swiper**

**Entry:** `src/EasingDefault, src/utils`
**Bundle:** `dist/EasingDefault.lynx.bundle` | Web: `dist/EasingDefault.web.bundle`

```ts {66-73}
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";
import { useAnimate } from "./useAnimate";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
  dataLength,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
  dataLength: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);
  const { animate, cancel: cancelAnimate } = useAnimate();
  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function calcNearestPage(offset: number) {
    "main thread";
    const nearestPage = Math.round(offset / itemWidth);
    return nearestPage * itemWidth;
  }

  function updateOffset(offset: number) {
    "main thread";

    const lowerBound = 0;
    const upperBound = -(dataLength - 1) * itemWidth;

    const realOffset = Math.min(lowerBound, Math.max(upperBound, offset));
    currentOffsetRef.current = realOffset;
    onOffsetUpdate(realOffset);
    const index = Math.round(-realOffset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
    cancelAnimate();
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: (offset) => {
        "main thread";
        updateOffset(offset);
      },
    });
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



We'll use this example to demonstrate value passing between main thread and background thread script.

### Main Thread Script Using Background Thread Script Values

First, we add a `duration` prop to the `<Swiper>` component to control the snap animation duration.

```tsx title="index.tsx"
<Swiper duration={300} />
```

Let's see how it works internally. When touch ends, `useOffset` calls the `animate` function to update the component position with animation effects. `animate` is a main thread function that accepts initial and target values and updates the component position according to the animation curve over the `duration` time.

```tsx title="useOffset.ts" {15-19}
function useOffset({
  duration,
}) {
  const currentOffsetRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    'main thread'
    // Update Component Offset
  }

  ...
  function handleTouchEnd() {
    'main thread'
    ...
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: updateOffset,
      duration,
    })
  }
}
```

Here, both `animate` and `handleTouchEnd` are main thread functions, and they can access the background thread value `duration`.

:::info Main Thread Functions Can Use Background Thread Values
Main thread script and background thread script run in separate runtimes and are isolated from each other.

However, to simplify main thread script development, Lynx automatically passes background thread values that main thread functions **depend on** to those functions, though this process has some limitations:

- The dependent background thread values must be serializable, so functions, `Promise`s, and other non-serializable values cannot be passed.
- Value passing only occurs during component `render`. If background thread values change after `render`, main thread functions won't be aware of these updates.

:::

### Background Thread Passing Main Thread Values

Next, we add a `main-thread:easing` prop to the `<Swiper>` component to allow users to customize the animation curve.

```tsx title="index.tsx" {6}
function easeInOut(x: number) {
  'main thread';
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
}

<Swiper main-thread:easing={easeInOut} />;
```

Inside the component, the main thread function `easeInOut` is passed to the background thread hook `useOffset`

```tsx title="Swiper.tsx" {2,6}
function Swiper({
  'main-thread:easing': MTEasing,
}) {
  ...
  const { handleTouchStart, ... } = useOffset({
    MTEasing,
  });
}
```

And in `useOffset`, it's passed to the main thread function `animate`.

```tsx title="useOffset.ts" {3,11}
function useOffset({
  duration,
  MTEasing,
}) {
  ...
  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    // ...
    animate({
      duration,
      easing: MTEasing,
    });
  }
}
```

:::info Main Thread Values Can Be Passed by Background Thread But Not Used
Main thread values, such as `MainThreadRef` and main thread functions, cannot be directly used by the background thread.

However, they can be passed by the background thread, such as being passed as `props` to components or as function parameters to other hooks or functions, and ultimately used in the main thread.
:::

:::details Add main-thread: Prefix for Props That Need Main Thread Functions
You may have noticed that when passing main thread functions or `MainThreadRef` as attributes, they need the `main-thread:` prefix, like `main-thread:ref` and `main-thread:bindtouchstart`.

By convention, when a prop expects a main thread function, it should have the `main-thread:` prefix, like `main-thread:easing`. We recommend following this convention for custom components too. This helps component users understand that the property requires a main thread function.

However, because variable names containing colons `:` are illegal in JavaScript, you need to rename these props when using them inside components.

```tsx title="Swiper.tsx"
function Swiper({ 'main-thread:easing': MTEasing }) {}
```

:::

Finally, we have a swiper with customizable animation curves.

**This is an example below:  swiper**

**Entry:** `src/Swiper, src/utils`
**Bundle:** `dist/Swiper.lynx.bundle` | Web: `dist/Swiper.web.bundle`

```tsx {15}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Summary

In this tutorial, we started with a simple `<Swiper>` component, gradually optimized its performance, and finally implemented a swiper with customizable animation curves.

We learned about:

- Using direct node manipulation to optimize performance
- Leveraging main thread script to enhance interaction experience
- Implementing communication between main thread and background thread
- Understanding value passing between main thread and background thread script



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

# Motion

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

## Add transitions for layout and style changes.

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

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

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

### Implement Collapse and Expand Effect for List Items

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

**This is an example below:  animation**

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

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

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

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

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

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

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

```



## Achieve stunning effects with keyframes.

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

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

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

### To achieve a rotation effect

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

**This is an example below:  animation**

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

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

.container {
  border: 1px solid red;
}

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

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

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

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

  100% {
    opacity: 0.5;
  }
}

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

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

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

```



### To achieve a spring effect

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

**This is an example below:  animation**

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```



## Create flexible keyframe animations in JS.

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

### To achieve a variable speed transform motions

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

**This is an example below:  animation**

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

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

import "./index.scss";

const AnimateAnimationExample = () => {
  return (
    <view style={{ width: "100%", height: "100%" }}>
      <view
        id="view1"
        className="box"
        bindtap={() => {
          const ani = lynx.getElementById("view1").animate(
            [
              {
                transform: "translate(0%, 0%) rotate(0deg)",
                "animation-timing-function": "linear",
              },
              {
                transform: "translate(200px, 0%) rotate(90deg)",
                "animation-timing-function": "cubic-bezier(.91,.03,.94,.11)",
              },
              {
                transform: "translate(200px, 100%) rotate(180deg)",
                "animation-timing-function": "linear",
              },
              {
                transform: "translate(0%, 100%) rotate(270deg)",
                "animation-timing-function": "cubic-bezier(.91,.03,.94,.11)",
              },
              {
                transform: "translate(0%, 0%) rotate(360deg)",
              },
            ],
            {
              name: "js-animation-1",
              duration: 5000,
              iterations: Infinity,
              easing: "linear",
            },
          );
        }}
      >
      </view>
    </view>
  );
};
root.render(<AnimateAnimationExample />);

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

```





---
url: /guide/styling/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>



---
url: /guide/styling/custom-theming.md
---

# Theming

Lynx supports a wide range of [CSS properties](/api/css/properties.md), enabling seamless integration with [CSS selectors](/api/css/selectors.md), [CSS variables](/api/css/properties/css-variable.md), and opt-in CSS inheritance. By defining and managing different theme variables, developers can easily switch between various color schemes, font styles, and other visual elements, ensuring an optimal visual experience and interaction for users.

## Using CSS Descendant Selectors to Switch Themes

Similar to web development, using descendant selectors by toggling the class of a parent element can affect the styles of all its descendant nodes, thus enabling the switching of multiple theme styles.

### Defining CSS Themes

First, multiple theme CSS styles need to be defined, with different themes having different properties such as colors and backgrounds. For example, we can define both light and dark theme styles, with the light mode defined using `.theme-light .content` and the dark mode defined using `.theme-dark .content`.

```css
/* light theme */
.theme-light .content {
  color: black;
  background-color: white;
}

/* dark theme */
.theme-dark .content {
  color: white;
  background-color: black;
}
```

### Applying CSS Styles

In the page, set the class of the ancestor node (can be defined in the [`page`](/api/elements/built-in/page.md#using-page-element-explicitly)) to `theme-dark` or `theme-light`, and set the class of the descendant nodes to `content`. In this way, the descendant nodes can be styled with `.theme-light .content` or `.theme-dark .content` styles.

```tsx
function App() {
  return (
    <view className="theme-dark">
      <view>
        <text className="content">text</text>
      </view>
    </view>
  );
}
```

### Switching Theme Styles

When the theme changes, switch the class of the ancestor node to `theme-dark` or `theme-light`, which will update the styles of the descendant nodes. In the Lynx development scenario, the front-end themes can be notified by the native client. For example, the native client can notify the front-end of theme changes by updating [globalProps](/api/lynx-api/lynx/lynx-global-props.md).

The corresponding front-end implementation:

```tsx
import { useMemo } from '@lynx-js/react';
import './App.css';

export function App() {
  const themeClass = useMemo(
    () => `theme-${lynx.__globalProps.appTheme}`,
    [lynx.__globalProps.appTheme],
  );

  return (
    //themeClass's value is 'theme-dark' or 'theme-light'
    <view className={themeClass}>
      <view>
        ...
        <text className="content">Hello Theme</text>
        ...
      </view>
    </view>
  );
}
```

### Example

**This is an example below:  css**

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

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

export default function App() {
  const [isDark, setIsDark] = useState(false);
  const themeClass = isDark ? "theme-dark" : "theme-light";

  const toggleTheme = () => {
    setIsDark(prev => !prev);
  };

  return (
    <view className={themeClass}>
      <view className="container">
        <view className="theme-card" bindtap={toggleTheme}>
          <text className="theme-icon">
            {isDark ? "🌙" : "☀️"}
          </text>
          <text className="title">
            {isDark ? "Dark Mode" : "Light Mode"}
          </text>
          <text className="subtitle">
            Tap to switch theme
          </text>
        </view>
        <view className="content-cards">
          <view className="card">
            <text className="card-title">Card Sample 1</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 2</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 3</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 4</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

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

```



## Using CSS Variables to Switch Themes

When using descendant selectors for theme switching, we need to predefine selectors for different theme styles, which lacks flexibility when dealing with multiple themes.

Using [CSS Variable](/api/css/properties/css-variable.md) to define theme styles and achieve theme switching by directly modifying the variable values.

### Defining CSS Themes

Similarly, we define the theme style variables that need to change and assign different values to the same variables.

For example, under different themes, `color` and `background-color` need to change with the theme. Therefore, two CSS variables `--color` and `--bg` need to be defined.

The descendant nodes can obtain the values of these variables in the stylesheet using `var(--color)` and `var(--bg)`.

```css
.theme-light {
  --color: black;
  --bg: white;
}

.content {
  color: var(--color);
  background-color: var(--bg);
}
```

### Applying CSS Styles

Note that CSS variables need to be mounted on the ancestor node (can be defined in the [`page`](/api/elements/built-in/page.md#using-page-element-explicitly)) so that their descendant nodes can use these variables in their respective stylesheets.

The descendant nodes can apply the values of these variables in `.content` using the `var(--*)` syntax.

```tsx
function App() {
  return (
    <view id="root" className="theme-light">
      <view>
        <text className="content">text</text>
      </view>
    </view>
  );
}
```

### Switching Theme Styles

#### Directly Changing CSS Variable Values with JS

Use JS API ([`setProperty`](/api/css/properties/css-variable.md#modifying-css-variables-via-javascript-api)) to directly modify CSS variable values, allowing flexible batch updates of CSS variables.

```tsx
import './App.css';

export function App() {
  const handleClick = () => {
    lynx.getElementById('root').setProperty({
      '--color': 'white',
      '--bg': 'black',
    });
  };

  return (
    <view id="root" className="theme-light" bindtap={handleClick}>
      <text className="content">Hello Variable</text>
    </view>
  );
}
```

#### Indirectly Changing Variable Values by Switching Classes

Alternatively, you can indirectly modify variable values by switching classes on the ancestor node that define different [CSS variables](/api/css/properties/css-variable.md#modifying-the-selector-that-declares-css-variables), triggering style updates for all child nodes using these variables when theme switching is needed.

For example, use `.theme-light` and `.theme-dark` to define CSS variable values for different themes:

```css
.theme-light {
  --color: black;
  --bg: white;
}

.theme-dark {
  --color: white;
  --bg: black;
}

.content {
  color: var(--color);
  background-color: var(--bg);
}
```

Switching between `.theme-light` or `.theme-dark` on the ancestor node changes the values of `--color` and `--bg`, which updates the styles for corresponding `.content` elements.

```tsx
import { useMemo } from '@lynx-js/react';

import './App.css';

export function App() {
  const themeClass = useMemo(
    () => `theme-${lynx.__globalProps.appTheme}`,
    [lynx.__globalProps.appTheme],
  );

  return (
    //themeClass's value is 'theme-dark' or 'theme-light'
    <view className={themeClass}>
      <text id="test" className="content">
        Hello Variable
      </text>
    </view>
  );
}
```

### Example

**This is an example below:  css**

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

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

export default function App() {
  const [isDark, setIsDark] = useState(false);
  const [useJS, setUseJS] = useState(false);
  const [showError, setShowError] = useState(false);
  const themeClass = isDark ? "theme-dark" : "theme-light";

  const toggleTheme = () => {
    if (useJS) {
      setShowError(true);
      setTimeout(() => setShowError(false), 3000);
      return;
    }

    setIsDark(prev => !prev);
  };

  const toggleThemeByJS = () => {
    setUseJS(true);
    const rootElement = lynx.getElementById("root");
    const newTheme = isDark ? "light" : "dark";

    if (rootElement) {
      if (isDark) {
        rootElement.setProperty({
          "--bg-primary": "#ffffff",
          "--bg-secondary": "#f5f5f5",
          "--text-primary": "#1a1a1a",
          "--text-secondary": "#666666",
          "--shadow": "rgba(0, 0, 0, 0.1)",
        });
      } else {
        rootElement.setProperty({
          "--bg-primary": "#2d2d2d",
          "--bg-secondary": "#1a1a1a",
          "--text-primary": "#ffffff",
          "--text-secondary": "#cccccc",
          "--shadow": "rgba(0, 0, 0, 0.3)",
        });
      }
      setIsDark(prev => !prev);
    }
  };

  return (
    <view id="root" className={themeClass}>
      <view className="container">
        <view className="theme-switchers">
          <view className="theme-card" bindtap={toggleTheme}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme by className</text>
          </view>
          <view className="theme-card" bindtap={toggleThemeByJS}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme through JS</text>
          </view>
        </view>
        <view className="content-cards">
          <view className="card">
            <text className="card-title">Card Sample 1</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 2</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 3</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 4</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
        </view>
      </view>
      {showError && (
        <view className="error-message-container">
          <text className="error-message">
            Cannot change variables through the class after modifying them in JS!
          </text>
        </view>
      )}
    </view>
  );
}

root.render(<App />);

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

```



## Leveraging CSS Inheritance As Needed

In pages with complex styles, using CSS inheritance can simplify development. However, implementing inheritance logic adds complexity to the style processing flow and can introduce some performance overhead. To optimize performance, Lynx does not enable inheritance for ordinary CSS properties by default, developers must enable it as needed. CSS custom properties (also known as CSS variables) are inherited by descendant nodes by default.

### Inheritance of CSS Custom Properties

[CSS Custom Properties](/api/css/properties/css-variable.md) (CSS variables, e.g., `--primary-color`) adhere to Web standards and are inherited by descendant nodes by default without additional configuration. Developers can define CSS custom properties in ancestor nodes to achieve dynamic style management.

### Inheritance of Regular (Non-Custom) Properties

To enable inheritance, configure[`enableCSSInheritance`](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md).

#### Default-Inheritable Properties

After enabling `enableCSSInheritance`, these properties can be inherited:

[`direction`](/api/css/properties/direction.md),[`color`](/api/css/properties/color.md),[`font-family`](/api/css/properties/font-family.md),[`font-size`](/api/css/properties/font-size.md),[`font-style`](/api/css/properties/font-style.md),[`font-weight`](/api/css/properties/font-weight.md),[`letter-spacing`](/api/css/properties/letter-spacing.md),[`line-height`](/api/css/properties/line-height.md),[`text-align`](/api/css/properties/text-align.md),[`text-decoration`](/api/css/properties/text-decoration.md),[`text-shadow`](/api/css/properties/text-shadow.md)

Default inherited properties inherit behavior alignment with [🌐W3C definition](https://www.w3.org/TR/css-cascade-3/#inheriting)

#### Custom-Inheritable Properties

In addition to the default inheritable properties, you can configure the page with [`customCSSInheritanceList`](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md)to define custom inheritable CSS properties. When there are custom inheritance declarations, only the CSS properties listed in the `customCSSInheritanceList` will be inheritable.

Example:

```json
"customCSSInheritanceList":["font-size","flex-direction"]
```

#### Limitations of CSS Inheritance

1. Elements with `position: fixed` will always inherit properties only from the page.
2. The keyword "inherit" is not supported.
3. In addition to the default inheritable properties, only CSS properties with types enum or boolean support custom inheritance.



---
url: /guide/styling/text-and-typography.md
---

# Typography

## Text in Lynx

In Lynx, the text content needs to be written inside the [`<text>`](/api/elements/built-in/text.md) element. This is different from HTML, where text can be directly written inside a `<div>`. Let's look at a simple example:

```tsx
//❌ This won't work
<view>hello world</view>

//✅ Use the <text> component
<text>hello world</text>
```

You can add styles to the `<text>` element to change the text effect. For example, to change the text color:

```tsx
<text style={{ color: 'red' }}>hello world</text>
```

Similarly, to change the text size and make the text italic:

```tsx
<text style={{ fontSize:"30px" }}>hello world</text>
<text style={{ fontStyle:"italic" }}>hello world</text>
```

Lynx also supports adding shadows or strokes to the text by setting the [`text-shadow`](/api/css/properties/text-shadow.md) and [`text-stroke`](/api/css/properties/text-stroke.md) properties to enrich the display effect:

**This is an example below:  text**

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

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

export default class TextShadowAndStrokeExample extends Component {
  render() {
    return (
      <view
        style={{
          display: "flex",
          flexDirection: "column",
          width: "100%",
          alignItems: "center",
        }}
      >
        <text style={{ textShadow: "2px 2px 4px green", fontSize: "30px" }}>
          Text Shadow
        </text>
        {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
        <text style={{ textStroke: "1px red", fontSize: "30px" }}>
          Text Stroke
        </text>
      </view>
    );
  }
}
root.render(<TextShadowAndStrokeExample />);

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

```



## Mixing Text with Different Styles

In daily text layout, it is often necessary to highlight some parts of the text, such as making keywords bold and changing their color. Suppose we want to make "important word" in the text "This is an important word" bold and red. We can put "important word" into an nested `<text>` and set the `color` and `font-weight` properties.

```tsx
<view>
  <text>
    This is an
    <text style={{ color: 'red', fontWeight: 'bold' }}>important word</text>
  </text>
</view>
```

You can use the properties in the CSS text module to control how text is displayed, such as line-breaking, alignment, and whitespace handling, to achieve more diverse text layout effects. For example, use [`text-indent`](/api/css/properties/text-indent.md) to control the first-line indentation of text, [`word-break`](/api/css/properties/word-break.md) to control the line-breaking behavior of words, and [`text-align`](/api/css/properties/text-align.md) to control the horizontal alignment of text content.

The following is an example of the comprehensive use of properties. You can also refer to [text-related properties](/api/elements/built-in/text.md#text-related-css-properties).

**This is an example below:  text**

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

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

export default class TextLayoutExample extends Component {
  render() {
    return (
      <view
        style={{
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          width: "100%",
        }}
      >
        <text
          style={{
            fontSize: "30px",
            color: "linear-gradient(to right, red,orange,yellow,green,blue,indigo,violet)",
          }}
        >
          Text Gradient Title
        </text>
        <text
          style={{ fontSize: "20px", textIndent: "20px", lineHeight: "30px" }}
        >
          You can
          <text style={{ fontWeight: "bold", fontSize: "20px" }}>
            {" "}
            bold
          </text>{" "}
          the text that needs to be emphasized.
          <text
            style={{
              backgroundImage: "linear-gradient(360deg, rgba(74, 170, 159, 0.2) 0%, rgba(74, 170, 159, 0) 100%)",
              backgroundSize: "100% 8px",
              backgroundPosition: "0 100%",
              backgroundRepeat: "no-repeat",
              fontSize: "20px",
            }}
          >
            You can add a gradual change to the background color of the text.
          </text>
          <text style={{ textDecoration: "underline", fontSize: "20px" }}>
            You can underline the sentence.
          </text>
        </text>
      </view>
    );
  }
}
root.render(<TextLayoutExample />);

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

```



## Implementing Text-Image Mixing Layout

To create more colorful pages, it is often necessary to embed images in text. The following describes how to mix text and images in layout. Take the following figure as an example:

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

```





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

# Composing Elements


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

## Element tag: UI Building Blocks

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

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

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

### Anatomy of an Element tag

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

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



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

# Flexible Box Layout

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

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

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

## Typical Features

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

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<FlexGrowExample />);

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

```



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

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<FlexShrinkExample />);

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

```



<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



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

# Grid Layout

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

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

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

## How to Build a Grid Layout?

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

### Basic Concepts

- **Grid Containers and Grid Items**

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

- **Grid Lines**

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

- **Grid Rows and Grid Columns**

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

- **Grid Cells**

  The intersection of rows and columns forms a grid cell.

- **Grid Areas**

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

- **Inline Axis and Block Axis**

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

<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



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

# Understanding Layout

Lynx provides:

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

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

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

## Sizing the Elements

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<SizingExample />);

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

```



<Details title={<span><code>box-sizing</code> is <code>border-box</code> by default and Lynx does not exhibit the behavior of margin collapsing.</span>}>
  By default, the size properties of Lynx, such as `width`, `height`, and `max-width`, describe the size of the border box. This is inconsistent with the default behavior of the Web.

  Lynx does not exhibit the behavior of [margin collapsing](https://developer.mozilla.org/en/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) as in the Web.
</Details>

## Layout the Elements

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

### Linear Layout

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<LinearExample />);

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

```



### Flexible Box Layout

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<FlexExample />);

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

```



### Grid Layout

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

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

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

root.render(<GridExample />);

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

```



### Relative Layout

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<RelativeExample />);

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

```



### Text and Inline Layout

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

## Aligning the Elements

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<AlignExample />);

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

```



## Offseting and Absolute Positioning

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

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<PositionExample />);

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

```



## Internationalization

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

<Tip title={`Enable CSS Inheritance and Logical Properties`}>
  Please refer to [CSS
  Inheritance](/guide/styling/custom-theming.md#how-to-enable-css-inheritance),
  using [`enableCSSInheritance`] to enable `direction` to be inheritable, and
  using logical properties depends on the `direction` value.
</Tip>

**This is an example below:  layout**

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

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

import "./index.scss";

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

root.render(<DirectionExample />);

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

```



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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



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

# Linear Layout

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

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

## How to Build a Linear Layout?

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

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

```css
display: linear;
```

### Step 2: Set the Layout Direction

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

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

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

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



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



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

# Managing Scrolling

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

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



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

# Styling with CSS

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

:::tip

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

:::

## Selectors and inline styles

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

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

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

**This is an example below:  css**

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

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

import "./index.css";

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

root.render(<App />);

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

```



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

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

### Nesting

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

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

/* equals */

.a {
  background: red;
}

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

## CSS cascading

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

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

**This is an example below:  css**

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

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

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

```



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

## CSS Variables and Opt-in Inheritance

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

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

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



---
url: /guide/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



---
url: /guide/use-native-modules.md
---

# Native Modules

When developing Lynx applications, you may encounter scenarios where you need to interact with native platform APIs not covered by Lynx. Or, you might want to reuse existing native platform code in your Lynx application. Regardless of the reason, you can use [**Native Modules**](/guide/spec.md#nativemodules) to seamlessly connect your JavaScript code with native code, allowing you to call native platform functions and APIs from your JavaScript code. The following will detail how to write a native module.

The basic steps for writing a native module are as follows:

1. Use TypeScript to **declare your typed interface specification**.
2. Use your interface specification to **write your Lynx application code**.
3. Follow your interface specification to **write your native platform code** and connect your native code to the Lynx runtime environment.

Next, this guide will demonstrate these steps through an example of building a native module.

:::info
Currently, native modules can only be used in [Background Thread Scripting](/guide/spec.md#background-thread-scripting).
:::

## Local Persistent Storage Module

This guide aims to show you how to write a local persistent storage module that enables your Lynx application to use JavaScript code to store data persistently locally.

To implement local persistent storage on mobile devices, you need to use the native APIs of Android, iOS and HarmonyOS:

- Android: [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences)
- iOS: [NSUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults)
- HarmonyOS: [Preferences](https://developer.huawei.com/consumer/en/doc/harmonyos-references/_preferences)

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



---
url: /api/css/at-rule.md
---

At-rules are CSS statements that instruct CSS how to behave. They begin with an at sign `@`, followed by an identifier and includes everything up to the next semicolon `;`, or the next CSS block, whichever comes first.

Here are the @rules supported by Lynx CSS, specified by their identifiers, each with a different syntax:



---
url: /api/css/at-rule/font-face.md
---

<APISummary />

The `@font-face` CSS at-rule specifies a custom font with which to display text;
the font can be loaded from either a remote server or a locally-installed font
on the user's own computer.

## Syntax

```css
@font-face {
  [ font-family: <string>; ] ||
  [ src: url(<string>) | local(<string>); ]
}
```

## Values

### `font-family`

Specifies a name that will be used as the font face value for `font` or `font-family` properties.

### `src`

Use a comma-separated list to specify available fonts. Use `url()` function for remote fonts and Base64-encoded fonts.Use `local()` function for local fonts.

:::info
On Android:use local(file://absolute/path) for absolute font paths
On iOS:use local(font-name) for system-installed font names (e.g. local(xxx-light))
:::

:::caution
Supported font formats:

Android: TTF, OTF, TTC

iOS: TTF, OTF, WOFF (iOS 10+), WOFF2 (iOS 10+)
:::

## Example

**This is an example below:  text**

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

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

import "./index.scss";

export default class FontFaceExample extends Component {
  render() {
    return (
      <view
        style={{
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          width: "100%",
        }}
      >
        <text>Whereas recognition of the inherent dignity</text>
        <text style={{ fontFamily: "Inter" }}>Whereas recognition of the inherent dignity</text>
        <text style={{ fontFamily: "Icon" }}>&#xEA01;</text>
      </view>
    );
  }
}
root.render(<FontFaceExample />);

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

```



## Difference from W3C

Not support font-style,font-weight and font-variant.

## Compatibility

**Compatibility Table**
**Query:** `css.at-rule.font-face`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/@font-face](https://developer.mozilla.org/zh-CN/docs/Web/CSS/@font-face)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/at-rule/import.md
---

The `@import` CSS at-rule is used to import style rules from other stylesheets.

## Syntax

```css
@import <string>;
```

See [string](/api/css/data-type/string.md) data type.

## Example

```css
@import 'custom.css';
@import './custom.css';
@import '/pages/card/index.css';
```



---
url: /api/css/at-rule/keyframes.md
---

The `@keyframes` CSS at-rule controls the intermediate steps in a CSS animation sequence by defining styles for keyframes (or waypoints) along the animation sequence.
This gives more control over the intermediate steps of the animation sequence than `transitions`.

## Implementation on platform

Both Android and iOS use keyframes to animate, the difference is that the property changes caused by Android animation will actually act on the View, while the transform part of iOS is implemented using CATransform3D.

## When properties are left out of some keyframes

Properties that aren't specified in every keyframe are interpolated if possible — properties that can't be interpolated are dropped from the animation. For example:

```css
@keyframes identifier {
  0% {
    background-color: blue;
    opacity: 0;
  }
  30% {
    opacity: 0.3;
  }
  72% {
    background-color: yellow;
  }
  100% {
    opacity: 1;
    background-color: red;
  }
}
```

## Keyframe value

- `from` A starting offset of 0%.

- `to` An ending offset of 100%.

- [`<percentage>`](/api/css/data-type/percentage.md) A percentage of the time through the animation sequence at which the specified keyframe should occur.

## Supported properties

The `keyframes` animation supports the `left`, `right`, `top`, `bottom`, `width`, `height`,`opacity`, `background-color`, `color`, `transform`, `transform-origin`, `max-width`, `min-width`, `max-height`, `min-height`, `padding-left`, `padding-right`, `padding-top`, `padding-bottom`, `margin-left`, `margin-right`, `margin-top`, `margin-bottom`, `border-left-width`, `border-right-width`, `border-top-width`, `border-bottom-width`, `border-left-color`, `border-right-color`, `border-top-color`, `border-bottom-color`, `flex-basis`, `flex-grow`, `filter`.



---
url: /api/css/data-type.md
---

CSS data types define typical values (including keywords and units) accepted by CSS properties and functions. They are a special kind of component value type.



---
url: /api/css/data-type/angle.md
---

# `<angle>`

<APISummary />

The `<angle>` CSS data type represents an angle value expressed in degrees, radians, or turns. It is used, for example, in `<gradient>` and in some `transform` functions.

## Syntax

The `<angle>` data type consists of a `<number>` followed by one of the units listed below. As with all dimensions, there is no space between the unit literal and the number. The angle unit is optional after the number 0.

Optionally, it may be preceded by a single + or - sign. Positive numbers represent clockwise angles, while negative numbers represent counterclockwise angles. For static properties of a given unit, any angle can be represented by various equivalent values. For example, `90deg` equals `-270deg`, and `1turn` equals `4turn`.

### Units

- `deg` Represents an angle in degrees. One full circle is 360deg. Examples: `0deg`, `90deg`, `14.23deg`.

- `rad` Represents an angle in radians. One full circle is 2π radians which approximates to `6.2832rad`. `1rad` is 180/π degrees. Examples: `0rad`, `1.0708rad`, `6.2832rad`.

- `turn` Represents an angle in a number of turns. One full circle is 1turn. Examples: `0turn`, `0.25turn`, `1.2turn`.

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.angle`

**Specifications:**
- [https://drafts.csswg.org/css-values/#angles](https://drafts.csswg.org/css-values/#angles)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;angle&gt;</code>




---
url: /api/css/data-type/color.md
---

# `<color>`

<APISummary />

The `<color>` CSS data type represents a color. A `<color>` may also include an alpha-channel transparency value, indicating how the color should composite with its background.

A `<color>` can be defined in any of the following ways:

Using a keyword (such as `blue` or `transparent`).
Using the `RGB cubic-coordinate system` (via the #-hexadecimal or the `rgb()` and `rgba()` functional notations).
Using the `HSL cylindrical-coordinate system` (via the `hsl()` and `hsla()` functional notations).

## Syntax

The `<color>` data type is specified using one of the options listed below.

### Named Color

Named colors are case-insensitive identifiers that represent a specific color, such as `red`, `blue`, `black`, or `lightseagreen`.

| Name                 | rgba function          | Live                                                                                                         |
| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| transparent          | rgba(0, 0, 0, 0)       | <div style={{ textAlign: 'center', margin: '-10px', backgroundColor: 'rgba(0, 0, 0, 0)' }}>transparent</div> |
| aliceblue            | rgba(240, 248, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 248, 255, 1)' }} />       |
| antiquewhite         | rgba(250, 235, 215, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 235, 215, 1)' }} />       |
| aqua                 | rgba(0, 255, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 255, 1)' }} />         |
| aquamarine           | rgba(127, 255, 212, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(127, 255, 212, 1)' }} />       |
| azure                | rgba(240, 255, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 255, 255, 1)' }} />       |
| beige                | rgba(245, 245, 220, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 245, 220, 1)' }} />       |
| bisque               | rgba(255, 228, 196, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 228, 196, 1)' }} />       |
| black                | rgba(0, 0, 0, 1)       | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 0, 1)' }} />             |
| blanchedalmond       | rgba(255, 235, 205, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 235, 205, 1)' }} />       |
| blue                 | rgba(0, 0, 255, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 255, 1)' }} />           |
| blueviolet           | rgba(138, 43, 226, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(138, 43, 226, 1)' }} />        |
| brown                | rgba(165, 42, 42, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(165, 42, 42, 1)' }} />         |
| burlywood            | rgba(222, 184, 135, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(222, 184, 135, 1)' }} />       |
| cadetblue            | rgba(95, 158, 160, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(95, 158, 160, 1)' }} />        |
| chartreuse           | rgba(127, 255, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(127, 255, 0, 1)' }} />         |
| chocolate            | rgba(210, 105, 30, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(210, 105, 30, 1)' }} />        |
| coral                | rgba(255, 127, 80, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 127, 80, 1)' }} />        |
| cornflowerblue       | rgba(100, 149, 237, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(100, 149, 237, 1)' }} />       |
| cornsilk             | rgba(255, 248, 220, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 248, 220, 1)' }} />       |
| crimson              | rgba(220, 20, 60, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(220, 20, 60, 1)' }} />         |
| cyan                 | rgba(0, 255, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 255, 1)' }} />         |
| darkblue             | rgba(0, 0, 139, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 139, 1)' }} />           |
| darkcyan             | rgba(0, 139, 139, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 139, 139, 1)' }} />         |
| darkgoldenrod        | rgba(184, 134, 11, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(184, 134, 11, 1)' }} />        |
| darkgray             | rgba(169, 169, 169, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(169, 169, 169, 1)' }} />       |
| darkgreen            | rgba(0, 100, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 100, 0, 1)' }} />           |
| darkgrey             | rgba(169, 169, 169, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(169, 169, 169, 1)' }} />       |
| darkkhaki            | rgba(189, 183, 107, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(189, 183, 107, 1)' }} />       |
| darkmagenta          | rgba(139, 0, 139, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(139, 0, 139, 1)' }} />         |
| darkolivegreen       | rgba(85, 107, 47, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(85, 107, 47, 1)' }} />         |
| darkorange           | rgba(255, 140, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 140, 0, 1)' }} />         |
| darkorchid           | rgba(153, 50, 204, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(153, 50, 204, 1)' }} />        |
| darkred              | rgba(139, 0, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(139, 0, 0, 1)' }} />           |
| darksalmon           | rgba(233, 150, 122, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(233, 150, 122, 1)' }} />       |
| darkseagreen         | rgba(143, 188, 143, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(143, 188, 143, 1)' }} />       |
| darkslateblue        | rgba(72, 61, 139, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(72, 61, 139, 1)' }} />         |
| darkslategray        | rgba(47, 79, 79, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(47, 79, 79, 1)' }} />          |
| darkslategrey        | rgba(47, 79, 79, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(47, 79, 79, 1)' }} />          |
| darkturquoise        | rgba(0, 206, 209, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 206, 209, 1)' }} />         |
| darkviolet           | rgba(148, 0, 211, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(148, 0, 211, 1)' }} />         |
| deeppink             | rgba(255, 20, 147, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 20, 147, 1)' }} />        |
| deepskyblue          | rgba(0, 191, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 191, 255, 1)' }} />         |
| dimgray              | rgba(105, 105, 105, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(105, 105, 105, 1)' }} />       |
| dimgrey              | rgba(105, 105, 105, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(105, 105, 105, 1)' }} />       |
| dodgerblue           | rgba(30, 144, 255, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(30, 144, 255, 1)' }} />        |
| firebrick            | rgba(178, 34, 34, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(178, 34, 34, 1)' }} />         |
| floralwhite          | rgba(255, 250, 240, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 250, 240, 1)' }} />       |
| forestgreen          | rgba(34, 139, 34, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(34, 139, 34, 1)' }} />         |
| fuchsia              | rgba(255, 0, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 0, 255, 1)' }} />         |
| gainsboro            | rgba(220, 220, 220, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(220, 220, 220, 1)' }} />       |
| ghostwhite           | rgba(248, 248, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(248, 248, 255, 1)' }} />       |
| gold                 | rgba(255, 215, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 215, 0, 1)' }} />         |
| goldenrod            | rgba(218, 165, 32, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(218, 165, 32, 1)' }} />        |
| gray                 | rgba(128, 128, 128, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 128, 128, 1)' }} />       |
| green                | rgba(0, 128, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 128, 0, 1)' }} />           |
| greenyellow          | rgba(173, 255, 47, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(173, 255, 47, 1)' }} />        |
| grey                 | rgba(128, 128, 128, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 128, 128, 1)' }} />       |
| honeydew             | rgba(240, 255, 240, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 255, 240, 1)' }} />       |
| hotpink              | rgba(255, 105, 180, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 105, 180, 1)' }} />       |
| indianred            | rgba(205, 92, 92, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(205, 92, 92, 1)' }} />         |
| indigo               | rgba(75, 0, 130, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(75, 0, 130, 1)' }} />          |
| ivory                | rgba(255, 255, 240, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 240, 1)' }} />       |
| khaki                | rgba(240, 230, 140, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 230, 140, 1)' }} />       |
| lavender             | rgba(230, 230, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(230, 230, 250, 1)' }} />       |
| lavenderblush        | rgba(255, 240, 245, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 240, 245, 1)' }} />       |
| lawngreen            | rgba(124, 252, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(124, 252, 0, 1)' }} />         |
| lemonchiffon         | rgba(255, 250, 205, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 250, 205, 1)' }} />       |
| lightblue            | rgba(173, 216, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(173, 216, 230, 1)' }} />       |
| lightcoral           | rgba(240, 128, 128, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 128, 128, 1)' }} />       |
| lightcyan            | rgba(224, 255, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(224, 255, 255, 1)' }} />       |
| lightgoldenrodyellow | rgba(250, 250, 210, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 250, 210, 1)' }} />       |
| lightgray            | rgba(211, 211, 211, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(211, 211, 211, 1)' }} />       |
| lightgreen           | rgba(144, 238, 144, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(144, 238, 144, 1)' }} />       |
| lightgrey            | rgba(211, 211, 211, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(211, 211, 211, 1)' }} />       |
| lightpink            | rgba(255, 182, 193, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 182, 193, 1)' }} />       |
| lightsalmon          | rgba(255, 160, 122, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 160, 122, 1)' }} />       |
| lightseagreen        | rgba(32, 178, 170, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(32, 178, 170, 1)' }} />        |
| lightskyblue         | rgba(135, 206, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(135, 206, 250, 1)' }} />       |
| lightslategray       | rgba(119, 136, 153, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(119, 136, 153, 1)' }} />       |
| lightslategrey       | rgba(119, 136, 153, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(119, 136, 153, 1)' }} />       |
| lightsteelblue       | rgba(176, 196, 222, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(176, 196, 222, 1)' }} />       |
| lightyellow          | rgba(255, 255, 224, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 224, 1)' }} />       |
| lime                 | rgba(0, 255, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 0, 1)' }} />           |
| limegreen            | rgba(50, 205, 50, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(50, 205, 50, 1)' }} />         |
| linen                | rgba(250, 240, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 240, 230, 1)' }} />       |
| magenta              | rgba(255, 0, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 0, 255, 1)' }} />         |
| maroon               | rgba(128, 0, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 0, 0, 1)' }} />           |
| mediumaquamarine     | rgba(102, 205, 170, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(102, 205, 170, 1)' }} />       |
| mediumblue           | rgba(0, 0, 205, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 205, 1)' }} />           |
| mediumorchid         | rgba(186, 85, 211, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(186, 85, 211, 1)' }} />        |
| mediumpurple         | rgba(147, 112, 219, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(147, 112, 219, 1)' }} />       |
| mediumseagreen       | rgba(60, 179, 113, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(60, 179, 113, 1)' }} />        |
| mediumslateblue      | rgba(123, 104, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(123, 104, 238, 1)' }} />       |
| mediumspringgreen    | rgba(0, 250, 154, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 250, 154, 1)' }} />         |
| mediumturquoise      | rgba(72, 209, 204, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(72, 209, 204, 1)' }} />        |
| mediumvioletred      | rgba(199, 21, 133, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(199, 21, 133, 1)' }} />        |
| midnightblue         | rgba(25, 25, 112, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(25, 25, 112, 1)' }} />         |
| mintcream            | rgba(245, 255, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 255, 250, 1)' }} />       |
| mistyrose            | rgba(255, 228, 225, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 228, 225, 1)' }} />       |
| moccasin             | rgba(255, 228, 181, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 228, 181, 1)' }} />       |
| navajowhite          | rgba(255, 222, 173, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 222, 173, 1)' }} />       |
| navy                 | rgba(0, 0, 128, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 128, 1)' }} />           |
| oldlace              | rgba(253, 245, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(253, 245, 230, 1)' }} />       |
| olive                | rgba(128, 128, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 128, 0, 1)' }} />         |
| olivedrab            | rgba(107, 142, 35, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(107, 142, 35, 1)' }} />        |
| orange               | rgba(255, 165, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 165, 0, 1)' }} />         |
| orangered            | rgba(255, 69, 0, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 69, 0, 1)' }} />          |
| orchid               | rgba(218, 112, 214, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(218, 112, 214, 1)' }} />       |
| palegoldenrod        | rgba(238, 232, 170, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(238, 232, 170, 1)' }} />       |
| palegreen            | rgba(152, 251, 152, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(152, 251, 152, 1)' }} />       |
| paleturquoise        | rgba(175, 238, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(175, 238, 238, 1)' }} />       |
| palevioletred        | rgba(219, 112, 147, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(219, 112, 147, 1)' }} />       |
| papayawhip           | rgba(255, 239, 213, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 239, 213, 1)' }} />       |
| peachpuff            | rgba(255, 218, 185, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 218, 185, 1)' }} />       |
| peru                 | rgba(205, 133, 63, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(205, 133, 63, 1)' }} />        |
| pink                 | rgba(255, 192, 203, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 192, 203, 1)' }} />       |
| plum                 | rgba(221, 160, 221, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(221, 160, 221, 1)' }} />       |
| powderblue           | rgba(176, 224, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(176, 224, 230, 1)' }} />       |
| purple               | rgba(128, 0, 128, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 0, 128, 1)' }} />         |
| red                  | rgba(255, 0, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 0, 0, 1)' }} />           |
| rosybrown            | rgba(188, 143, 143, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(188, 143, 143, 1)' }} />       |
| royalblue            | rgba(65, 105, 225, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(65, 105, 225, 1)' }} />        |
| saddlebrown          | rgba(139, 69, 19, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(139, 69, 19, 1)' }} />         |
| salmon               | rgba(250, 128, 114, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 128, 114, 1)' }} />       |
| sandybrown           | rgba(244, 164, 96, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(244, 164, 96, 1)' }} />        |
| seagreen             | rgba(46, 139, 87, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(46, 139, 87, 1)' }} />         |
| seashell             | rgba(255, 245, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 245, 238, 1)' }} />       |
| sienna               | rgba(160, 82, 45, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(160, 82, 45, 1)' }} />         |
| silver               | rgba(192, 192, 192, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(192, 192, 192, 1)' }} />       |
| skyblue              | rgba(135, 206, 235, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(135, 206, 235, 1)' }} />       |
| slateblue            | rgba(106, 90, 205, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(106, 90, 205, 1)' }} />        |
| slategray            | rgba(112, 128, 144, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(112, 128, 144, 1)' }} />       |
| slategrey            | rgba(112, 128, 144, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(112, 128, 144, 1)' }} />       |
| snow                 | rgba(255, 250, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 250, 250, 1)' }} />       |
| springgreen          | rgba(0, 255, 127, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 127, 1)' }} />         |
| steelblue            | rgba(70, 130, 180, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(70, 130, 180, 1)' }} />        |
| tan                  | rgba(210, 180, 140, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(210, 180, 140, 1)' }} />       |
| teal                 | rgba(0, 128, 128, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 128, 128, 1)' }} />         |
| thistle              | rgba(216, 191, 216, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(216, 191, 216, 1)' }} />       |
| tomato               | rgba(255, 99, 71, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 99, 71, 1)' }} />         |
| turquoise            | rgba(64, 224, 208, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(64, 224, 208, 1)' }} />        |
| violet               | rgba(238, 130, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(238, 130, 238, 1)' }} />       |
| wheat                | rgba(245, 222, 179, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 222, 179, 1)' }} />       |
| white                | rgba(255, 255, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 255, 1)' }} />       |
| whitesmoke           | rgba(245, 245, 245, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 245, 245, 1)' }} />       |
| yellow               | rgba(255, 255, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 0, 1)' }} />         |
| yellowgreen          | rgba(154, 205, 50, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(154, 205, 50, 1)' }} />        |

### RGB Color Model

`RGB` colors can be expressed through both hexadecimal (prefixed with #) and functional (`rgb()`, `rgba()`) notations.

#### Syntax

- hexadecimal: `#RGB[A]` or `#RRGGBB[AA]`
  `R` (red), `G` (green), `B` (blue), and `A` (alpha) are hexadecimal characters (0-9, A-F). `A` is optional. For example, `#ff0000` is equivalent to `#ff0000ff`. The three-digit notation (`#RGB`) is a shorter version of the six-digit form (`#RRGGBB`). For example, `#f09` is the same color as `#ff0099`. Likewise, the four-digit RGB notation (`#RGBA`) is a shorter version of the eight-digit form (`#RRGGBBAA`). For example, `#0f38` is the same color as `#00ff3388`.

- `rgb()` or `rgba()`
  `R` (red), `G` (green), and `B` (blue) can be either [`<number>`](/api/css/data-type/number.md)s or [`<percentage>`](/api/css/data-type/percentage.md)s, where the number `255` corresponds to `100%`. `A` (alpha) can be a [`<number>`](/api/css/data-type/number.md) between 0 and 1, or a [`<percentage>`](/api/css/data-type/percentage.md), where the number `1` corresponds to `100%` (full opacity).

### HSL Color Model

The HSL color model defines a given color according to its hue, saturation, and lightness components. An optional alpha component represents the color's transparency.

#### Syntax

HSL colors are expressed through the functional `hsl()` and `hsla()` notations.

`hsl()` or `hsla()`:`hsl[a](H, S, L[, A])`

- `H` (hue) is an [`<angle>`](/api/css/data-type/angle.md) of the color circle given in `deg`s, `rad`s, `grad`s. When written as a unitless [`<number>`](/api/css/data-type/number.md), it is interpreted as degrees. By definition, red=0deg=360deg, with the other colors spread around the circle, so green=120deg, blue=240deg, etc.
- `S` (saturation) and `L` (lightness) are percentages. `100%` **saturation** is completely saturated, while `0%` is completely unsaturated (gray). `100%` **lightness** is white, `0%` lightness is black, and `50%` lightness is "normal".
- `A` (alpha) can be a [`<number>`](/api/css/data-type/number.md) between 0 and 1, or a [`<percentage>`](/api/css/data-type/percentage.md), where the number `1` corresponds to `100%` (full opacity).

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.color`

**Specifications:**
- [https://drafts.csswg.org/css-values/#colors](https://drafts.csswg.org/css-values/#colors)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay macOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;color&gt;</code>




---
url: /api/css/data-type/fit-content.md
---

# `<fit-content>`

<APISummary />

`fit-content()` currently supports for [`width`], [`height`] and [grid layout] properties ([`grid-template-columns`], [`grid-template-rows`], [`grid-auto-columns`], and [`grid-auto-rows`]).

When used as a [`width`] or [`height`], take the larger value between the following two: the maximum size of the content and the smaller value specified in `fit-content()`.

`fit-content` is equivalent to `fit-content(auto)`, and the specified value of auto is the same as the corresponding axis length of the parent element.

## Example

```css
width: fit-content;
height: fit-content(200px);
grid-template-columns: fit-content;
grid-template-rows: fit-content;
grid-auto-columns: fit-content;
grid-auto-rows: fit-content;
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.fit-content`

**Specifications:**
- [https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content](https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | targetSdkVersion 2.0 | - |
| iOS | targetSdkVersion 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ✅ Yes | - |


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

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

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

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

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

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

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



---
url: /api/css/data-type/gradient.md
---

# `<gradient>`

<APISummary />

The `<gradient>` CSS data type is a special type of `<image>` that consists of a progressive transition between two or more colors.

## Syntax

The `<gradient>` data type is defined with one of the function types listed below.

### Linear gradient

Linear gradients transition colors progressively along an imaginary line. They are generated with the `linear-gradient()` function.

```css
/* A gradient tilted 45 degrees, starting blue and finishing red */
linear-gradient(45deg, blue, red);
/* A gradient going from the bottom right to the top left corner, starting blue and finishing red */
linear-gradient(to left top, blue, red);
/* Color stop: A gradient going from the bottom to top, starting blue, turning green at 40% of its length, and finishing red */
linear-gradient(0deg, blue, green 40%, red);
```

#### Formal Syntax

```
linear-gradient([ <angle> | to <side-or-corner> ,]? <color-stop> [ , <color-stop> ]+ )
```

#### Values

- `<side-or-corner>`
  The position of the gradient line's starting point. If specified, it consists of the word `to` and up to two keywords: one indicates the horizontal side (`left` or `right`), and the other the vertical side (`top` or `bottom`). The order of the side keywords does not matter. If unspecified, it defaults to `to bottom`. <br />
  The values `to top`, `to bottom`, `to left`, and `to right` are equivalent to the angles `0deg`, `180deg`, `270deg`, and `90deg`, respectively. The other values are translated into an angle.

- `<angle>`
  The gradient line's angle of direction. A value of `0deg` is equivalent to `to top`; increasing values rotate clockwise from there.

- `<color-stop>`
  A color-stop's [`<color>`](/api/css/data-type/color.md) value, followed by one stop position, a [`<percentage>`](/api/css/data-type/percentage.md) value along the gradient's axis.

### Radial Gradient

Radial gradients transition colors progressively from a center point (origin). They are generated with the `radial-gradient()` function.

```css
radial-gradient(#e66465, #9198e5);

radial-gradient(closest-side, #3f87a6, #ebf8e1, #f69d3c);

radial-gradient(circle at 100%, #333, #333 50%, #eee 75%, #333 75%);

radial-gradient(ellipse at top, #e66465, transparent);
```

#### Formal Syntax

```
radial-gradient(
  [ [ circle || <length> ]                         [ at <position> ]? , |
    [ ellipse || [ <length> | <percentage> ]{2} ]  [ at <position> ]? , |
    [ [ circle | ellipse ] || <extent-keyword> ] [at <position> ]? , |
    at <position> ,
  ]?
  <color-stop> [ , <color-stop> ]+
)
```

#### Values

- `<position>`
  The position of the gradient, interpreted in the same way as [`background-position`](/api/css/properties/background-position.md) or [`transform-origin`](/api/css/properties/transform-origin.md). If unspecified, it defaults to center.

- `<ending-shape>`
  The gradient's ending-shape. The value can be `circle` (meaning that the gradient's shape is a circle with a constant radius) or `ellipse` (meaning that the shape is an axis-aligned ellipse). If unspecified, it defaults to `ellipse`.

- `<size>`
  Determines the size of the gradient's ending shape. <br />
  If omitted it defaults to farthest-corner. It can be given explicitly or by keyword. For the purpose of the keyword definitions, consider the gradient box edges as extending infinitely in both directions, rather than being finite line segments.

  | **Keyword**       | **Description**                                                                                                                                                                 |
  | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `closest-side`    | The gradient's ending shape meets the side of the box closest to its center (for circles) or meets both the vertical and horizontal sides closest to the center (for ellipses). |
  | `closest-corner`  | The gradient's ending shape is sized so that it exactly meets the closest corner of the box from its center.                                                                    |
  | `farthest-side`   | Similar to `closest-side`, except the ending shape is sized to meet the side of the box farthest from its center (or vertical and horizontal sides).                            |
  | `farthest-corner` | The default value, the gradient's ending shape is sized so that it exactly meets the farthest corner of the box from its center.                                                |

- `<color-stop>`
  Same as `linear-gradient`

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.gradient`

**Specifications:**
- [https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content](https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;gradient&gt;</code>




---
url: /api/css/data-type/length-percentage.md
---

# `<length-percentage>`

<APISummary />

Equivalent to \[ [`<length>`] ｜ [`<percentage>`] ] with [`<percentage>`] will resolve to a [`<length>`]. Additionally support `calc()` math expression.

## Syntax

A `<length-percentage>` can be a [`<length>`], a [`<percentage>`] or a `calc()` math expression. The `calc()` function is a math function that allows basic arithmetic to be performed on numerical values, using addition (+), subtraction (-), multiplication (\*), division (/), and parentheses.

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.length-percentage`

**Specifications:**
- [https://drafts.csswg.org/css-values/#typedef-length-percentage](https://drafts.csswg.org/css-values/#typedef-length-percentage)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;length-percentage&gt;</code>


[`<percentage>`]: /api/css/data-type/percentage.md

[`<length>`]: /api/css/data-type/length.md



---
url: /api/css/data-type/length.md
---

# `<length>`

<APISummary />

The `<length>` CSS data type represents a distance value.

## Syntax

The `<length>` data type consists of a `<number>` followed by one of the units listed below. As with all CSS dimensions, there is no space between the number and the unit literal. Specifying the length unit is optional if the number is 0.

_Without units other than 0 is not supported_

## Units

#### Relative length units

Relative lengths represent a measurement in terms of some other distance. Depending on the unit, this distance can be the size of a specific character, the line height, or the size of the `viewport`.

- `rpx`: Responsive pixel. It can be adapted according to the screen width. The specified screen width is `750rpx`. For example, on iPhone6's the screen width is `375px`, and there are `750` physical pixels in total, then `750rpx = 375px = 750ppx`, `1rpx = 0.5px = 1ppx`.

- `rem`: This unit represents the `font-size` of the root element. When used on the `font-size` of the root element, it represents its initial value.

- `em`: This unit represents the calculated value of the element's `font-size`. If used in the `font-size` property itself, it represents the `font-size` value inherited by the element.

- `vh`: `1vh` is 1% of the viewport height.

- `vw`: `1vw` is 1% of the viewport width.

#### Absolute length units

Absolute length units represent a physical measurement when the physical properties of the output medium are known, such as for print layout. This is done by anchoring one of the units to a physical unit and then defining the others relative to it. The anchoring is done differently for low-resolution devices and high-resolution devices.

- `px`: Pixel, equal to a physical pixel multiplied by pixel density, equivalent to `pt` on iOS or `dp` on Android. For high-resolution screens, one CSS pixel implies multiple device pixels. E.g: `1px` = `1/96th of 1in`.

- `ppx`: Physical pixel, equal to the size of an actual pixel on the screen.

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.length`

**Specifications:**
- [https://drafts.csswg.org/css-values/#lengths](https://drafts.csswg.org/css-values/#lengths)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;length&gt;</code>




---
url: /api/css/data-type/max-content.md
---

# `<max-content>`

<APISummary />

`max-content` currently supports for [`width`], [`height`] and [grid layout] properties ([`grid-template-columns`], [`grid-template-rows`], [`grid-auto-columns`], and [`grid-auto-rows`]).

## Example

```css
width: max-content;
grid-template-columns: max-content;
grid-template-rows: max-content;
grid-auto-columns: max-content;
grid-auto-rows: max-content;
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.max-content`

**Specifications:**
- [https://drafts.csswg.org/css-sizing-3/#valdef-width-max-content](https://drafts.csswg.org/css-sizing-3/#valdef-width-max-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | targetSdkVersion 2.0 | - |
| iOS | targetSdkVersion 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ✅ Yes | - |


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

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

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

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

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

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

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



---
url: /api/css/data-type/number.md
---

# `<number>`

<APISummary />

The `<number>` CSS data type represents a number, being either an integer or a number with a fractional component.

## Examples

### Valid numbers

```css
12          A raw <integer> is also a <number>.
4.01        Positive fraction
-456.8      Negative fraction
0.0         Zero
+0.0        Zero, with a leading +
-0.0        Zero, with a leading -
.60         Fractional number without a leading zero
10e3        Scientific notation
-3.4e-2     Complicated scientific notation
```

### Invalid numbers

```css
12.         Decimal points must be followed by at least one digit.
+-12.2      Only one leading +/- is allowed.
12.1.1      Only one decimal point is allowed.
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.number`

**Specifications:**
- [https://drafts.csswg.org/css-values/#number](https://drafts.csswg.org/css-values/#number)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;number&gt;</code>




---
url: /api/css/data-type/percentage.md
---

# `<percentage>`

<APISummary />

The `<percentage>` CSS data type represents a percentage value. It is often used to define a size as relative to an element's parent object. Numerous properties can use percentages, such as width, height, margin, padding, and font-size.

The `<percentage>` data type consists of a [`<number>`](/api/css/data-type/number.md) followed by the percentage sign (%). As with all CSS dimensions, there is no space between the symbol and the number.

## Examples

```tsx
<view>
  <text style={{ width: '50%', marginLeft: '20%', backgroundColor: '#00FF00' }}>
    Width: 50%, Left margin: 20%
  </text>
  <text style={{ width: '30%', marginLeft: '60%', backgroundColor: '#FF0000' }}>
    Width: 30%, Left margin: 60%
  </text>
</view>
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.percentage`

**Specifications:**
- [https://drafts.csswg.org/css-values/#percentages](https://drafts.csswg.org/css-values/#percentages)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;percentage&gt;</code>




---
url: /api/css/data-type/string.md
---

# `<string>`

<APISummary />

The `<string>` CSS data type represents a sequence of characters.

## Syntax

The `<string>` data type is composed of any number of [Unicode](https://en.wikipedia.org/wiki/Unicode) characters surrounded by either double (`"`) or single (`'`) quotes.

Most characters can be represented literally. All characters can also be represented with their respective [Unicode code points](https://en.wikipedia.org/wiki/Unicode#Code_point_planes_and_blocks) in hexadecimal, in which case they are preceded by a backslash (`\`). For example, `\22` represents a double quote, `\27` a single quote (`'`), and `\A9` the copyright symbol (`©`).

Importantly, certain characters which would otherwise be invalid can be escaped with a backslash. These include double quotes when used inside a double-quoted string, single quotes when used inside a single-quoted string, and the backslash itself. For example, `\\` will create a single backslash.

To output new lines, you must escape them with a line feed character such as `\A` or `\00000A`. In your code, however, strings can span multiple lines, in which case each new line must be escaped with a `\` as the last character of the line.

## Examples

```css
/* Simple strings */
"This string is demarcated by double quotes."
'This string is demarcated by single quotes.'

/* Character escaping */
"This is a string with \" an escaped double quote."
"This string also has \22 an escaped double quote."
'This is a string with \' an escaped single quote.'
'This string also has \27 an escaped single quote.'
"This is a string with \\ an escaped backslash."
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.string`

**Specifications:**
- [https://drafts.csswg.org/css-values/#string](https://drafts.csswg.org/css-values/#string)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;string&gt;</code>




---
url: /api/css/data-type/time.md
---

# `<time>`

<APISummary />

The `<time>` CSS data type represents a time value expressed in seconds or milliseconds. It is used in `animation`, `transition`, and related properties.

## Syntax

The `<time>` data type consists of a `<number>` followed by one of the units listed below. Optionally, it may be preceded by a single `+` or `-` sign. As with all dimensions, there is no space between the unit literal and the number.

### Units

- `s` Represents a time in seconds. Examples: `0s`, `1.5s`, `-60s`.

- `ms` Represents a time in milliseconds. Examples: `0ms`, `150.25ms`, `-60000ms`.

## Examples

### Valid times

```
12s         Positive integer
-456ms      Negative integer
4.3ms       Non-integer
14mS        The unit is case-insensitive, although capital letters are not recommended.
+0s         Zero with a leading + and a unit
-0ms        Zero with a leading - and a unit
```

### Invalid times

```
0           Although unitless zero is allowed for <length>s, it's invalid for <time>s.
12.0        This is a <number>, not a <time>, because it's missing a unit.
7 ms        No space is allowed between the number and the unit.
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.time`

**Specifications:**
- [https://drafts.csswg.org/css-values/#time](https://drafts.csswg.org/css-values/#time)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;time&gt;</code>




---
url: /api/css/properties.md
---




---
url: /api/css/properties/-x-auto-font-size-preset-sizes.md
---

# -x-auto-font-size-preset-sizes

<APISummary />

## Description

The `-x-auto-font-size-preset-sizes` property specifies an array of preset font sizes. When text auto-scaling is enabled, the most suitable font size will be selected from this array - the largest size that satisfies the width constraints.

## Examples

**This is an example below:  css-api**

**Entry:** `src/-x-auto-font-size-preset-sizes`
**Bundle:** `dist/-x-auto-font-size-preset-sizes.lynx.bundle`

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

const XAutoFontSizePresetSizes = () => {
  const containerStyle = {
    display: "linear" as const,
    backgroundColor: "white",
  };

  const baseTextStyle = {
    backgroundColor: "gray",
    fontSize: "20px",
    overflow: "hidden",
  };

  const autoFontStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
  };

  const autoFontWithSizeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px",
  };

  const autoFontWithRangeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px",
  };

  const autoFontWithStepStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px 3px",
  };

  const presetSizesStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
    XAutoFontSizePresetSizes: "10px 16px 25px",
  };

  const sampleText = "This is a test text for auto-sizing font This is a test text for auto-sizing font";

  return (
    <view className="intro" style={containerStyle}>
      <text text-maxline="1" style={autoFontStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithSizeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithRangeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithStepStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={presetSizesStyle}>
        {sampleText}
      </text>
    </view>
  );
};

root.render(<XAutoFontSizePresetSizes />);

```



## Syntax

```css
-x-auto-font-size: true;
-x-auto-font-size-preset-sizes: 10px 12px 15px;
```

## Formal definition


<PropertyDefinition initialValue={<>[]</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
-x-auto-font-size-preset-sizes = (<length>){3}
```

## Differences from the Web

- This is a Lynx-specific property.

## Notes

- This property is only effective when `-x-auto-font-size` is enabled, and it overrides the minimum and maximum font size settings in `-x-auto-font-size`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-auto-font-size-preset-sizes`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.2 | - |
| Clay iOS | 3.2 | - |
| Clay Windows | 3.2 | - |
| Clay macOS | 3.2 | - |
| Web | ❓ Unknown | - |




---
url: /api/css/properties/-x-auto-font-size.md
---

# -x-auto-font-size

<APISummary />

## Introduction

The `-x-auto-font-size` property sets whether to enable text adaptive font size adjustment, minimum text font size, maximum text font size, and font size adjustment granularity value. All parameters except the first one are optional.

## Examples

**This is an example below:  css-api**

**Entry:** `src/-x-auto-font-size`
**Bundle:** `dist/-x-auto-font-size.lynx.bundle`

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

const XAutoFontSize = () => {
  const containerStyle = {
    display: "linear" as const,
    backgroundColor: "white",
  };

  const baseTextStyle = {
    backgroundColor: "gray",
    fontSize: "20px",
    overflow: "hidden",
  };

  const autoFontStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
  };

  const autoFontWithSizeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px",
  };

  const autoFontWithRangeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px",
  };

  const autoFontWithStepStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px 3px",
  };

  const presetSizesStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
    XAutoFontSizePresetSizes: "10px 16px 25px",
  };

  const sampleText = "This is a test text for auto-sizing font This is a test text for auto-sizing font";

  return (
    <view className="intro" style={containerStyle}>
      <text text-maxline="1" style={autoFontStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithSizeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithRangeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithStepStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={presetSizesStyle}>
        {sampleText}
      </text>
    </view>
  );
};

root.render(<XAutoFontSize />);

```



## Syntax

```css
-x-auto-font-size: 'true';
-x-auto-font-size: 'true 10px';
-x-auto-font-size: 'true 10px 30px';
-x-auto-font-size: 'true 10px 30px 2px';
```

### Values

- First parameter indicates whether to enable text adaptive font size adjustment, 'true' to enable, 'false' to disable

- Second parameter specifies the minimum text font size, value is [`<length>`](/api/css/data-type/length.md), this parameter is optional

- Third parameter specifies the maximum text font size, value is [`<length>`](/api/css/data-type/length.md), this parameter is optional when the first two parameters exist

- Fourth parameter specifies the font size adjustment granularity value, value is [`<length>`](/api/css/data-type/length.md), this parameter is optional when the first three parameters exist, default value is 1px

## Formal definition


<PropertyDefinition initialValue={<>false</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
-x-auto-font-size = true (<length>){0,3} | false
```

## Differences from Web

- This is a Lynx-specific property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-auto-font-size`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.2 | - |
| Clay iOS | 3.2 | - |
| Clay Windows | 3.2 | - |
| Clay macOS | 3.2 | - |
| Web | ❌ No | - |




---
url: /api/css/properties/-x-handle-color.md
---

# -x-handle-color

<APISummary />

## Introduction

The `-x-handle-color` property specifies the color of the floating marker when copying text, only valid in the selection pseudo-element.

## Examples

**This is an example below:  css-api**

**Entry:** `src/-x-handle-color`
**Bundle:** `dist/-x-handle-color.lynx.bundle`

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

const XHandleColor = () => {
  return (
    <view className="container">
      <text className="text1" text-selection={true} flatten={false}>This is a text</text>
      <text className="text2" text-selection={true} flatten={false}>This is a text</text>
    </view>
  );
};

root.render(<XHandleColor />);

```



## Syntax

```css
::selection {
  -x-handle-color: blue;
}
```

### Values

- [`<color>`](/api/css/properties/color.md)<br />
  Sets the color of the floating marker

## Formal definition


<PropertyDefinition initialValue={<>false</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
-x-handle-color = <color>
```

## Differences from web

- This is a Lynx-specific property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-handle-color`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ❌ No | - |




---
url: /api/css/properties/-x-handle-size.md
---

# -x-handle-size

<APISummary />

## Introduction

The `-x-handle-size` property specifies the size of the floating marker when copying text, only valid in the selection pseudo-element.

## Examples

**This is an example below:  css-api**

**Entry:** `src/-x-handle-size`
**Bundle:** `dist/-x-handle-size.lynx.bundle`

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

const XHandleSize = () => {
  return (
    <view className="container">
      <text className="text1" text-selection={true} flatten={false}>This is a text</text>
      <text className="text2" text-selection={true} flatten={false}>This is a text</text>
    </view>
  );
};

root.render(<XHandleSize />);

```



## Syntax

```css
::selection {
  -x-handle-size: 5px;
}
```

### Values

- [`<length>`](/api/css/data-type/length.md)<br />
  Sets the size of the floating marker

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
-x-handle-size = <length>
```

## Differences from web

- This is a Lynx-specific property.

## Notes

- On Android, it corresponds to the size of the entire floating marker, while on iOS, it corresponds to the diameter of the floating marker's circular ball

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-handle-size`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ❌ No | - |




---
url: /api/css/properties/align-content.md
---

<APISummary />

## Introduction

In [flexible box layout](/guide/ui/layout/flexible-box-layout.md), the `align-content` property defines how flex lines are aligned along the **cross-axis**.

In [grid layout](/guide/ui/layout/grid-layout.md), the `align-content` property defines how to align grid tracks along the **block axis**.

## Examples

**This is an example below:  css-api**

**Entry:** `src/align-content`
**Bundle:** `dist/align-content.lynx.bundle`

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

const AlignContent = () => {
  const colorBlockStyle = (color: string) => ({
    width: "100px",
    height: "50px",
    backgroundColor: color,
  });

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text>align-content:stretch;</text>
        <view className="container1">
          <view style={colorBlockStyle("red")} />
          <view style={colorBlockStyle("yellow")} />
          <view style={colorBlockStyle("green")} />
          <view style={colorBlockStyle("blue")} />
        </view>
        <text>align-content:center;</text>
        <view className="container2">
          <view style={colorBlockStyle("red")} />
          <view style={colorBlockStyle("yellow")} />
          <view style={colorBlockStyle("green")} />
          <view style={colorBlockStyle("blue")} />
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<AlignContent />);

```



## Syntax

### Values

#### `stretch`

**Default value**. If the combined size of the items along the cross axis (block axis in grid layout) is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container along the cross axis (block axis in grid layout).

#### `start`

All lines are packed starting from the start edge of the container.

#### `end`

All lines are packed starting from the end edge of the container.

#### `flex-start`

Behaves the same as `start`. Recommended to use only in flexible box layout.

#### `flex-end`

Behaves the same as `end`. Recommended to use only in flexible box layout.

#### `center`

All lines are packed toward the center of the container. Lines are tightly packed against each other and aligned centrally within the container. The distance between the cross-axis (block axis in grid layout) start edge and the first line equals the distance between the cross-axis (block axis in grid layout) end edge and the last line.

#### `space-between`

Lines are evenly distributed in the container. The spacing between each pair of adjacent lines is equal. The cross-axis (block axis in grid layout) start edge and end edge of the container are flush with the first and last lines respectively.

#### `space-around`

Lines are evenly distributed in the container, with equal space between lines. The space between the cross-axis (block axis in grid layout) start edge and the first line, and between the cross-axis (block axis in grid layout) end edge and the last line, is half the size of the space between adjacent lines.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>stretch</code>
  </>
}
  appliesTo={<>flex containers/grid containers</>}
  inherited="no"
  animatable="no"
/>

## Formal syntax

```
align-content = stretch | start | end | flex-start | flex-end | center | space-between | space-around
```

## Differences from web

[mdn: align-content](https://developer.mozilla.org/en/docs/Web/CSS/align-content)

1. `normal`, `baseline`, `first baseline`, and `last baseline` are not supported. Initial value is `stretch`.
2. `space-evenly` is not supported, will be supported in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.align-content`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-content](https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/align-items.md
---

<APISummary />

## Introduction

`align-items` property sets the [`align-self`](/api/css/properties/align-self.md) value on all direct children as a group. In flexible box layout and [linear layout](/guide/ui/layout/linear-layout.md), it controls the alignment of items on the **cross axis**. In grid layout, it controls the alignment of items on the **block axis** within their grid area.

For flexible box layout, if any child element's cross-axis [`margin`](/api/css/properties/margin.md) is set to `auto`, `align-items` will be ignored.

:::info
For grid layout, Lynx doesn't support `writing-mode`, so the block axis is the vertical axis.
:::

## Examples

**This is an example below:  css-api**

**Entry:** `src/align-items`
**Bundle:** `dist/align-items.lynx.bundle`

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

const AlignItems = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const itemStyle = {
    width: "50px",
    height: "50px",
    margin: "5px",
    backgroundColor: "#4e98f4",
    color: "#ffffff",
    textAlign: "center" as const,
    lineHeight: "50px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="title">align-items: stretch;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "stretch" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
        </view>

        <text className="title">align-items: center;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
        </view>

        <text className="title">align-items: flex-start;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "flex-start" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
        </view>

        <text className="title">align-items: flex-end;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "flex-end" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>XS</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<AlignItems />);

```



## Syntax

### Values

#### `stretch`

**Default value**. If items are smaller than the container in the **cross-axis** direction (block axis in [grid](/guide/ui/layout/grid-layout.md) layout), items with unspecified dimensions (height/width) or set to `auto` will be stretched to match the height of the row or width of the column. These items still maintain their aspect ratio constraints.

#### `center`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, items are centered along the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, items are centered along the block axis within their grid area.

:::info
In flexible box layout, if an item's cross-axis size is larger than the flex container, it will overflow equally in both directions.
:::

#### `start`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, items are aligned at the start of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, items are aligned with the start edge of their grid area along the block axis.

#### `end`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, items are aligned at the end of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, items are aligned with the end edge of their grid area along the block axis.

#### `flex-start`

Behaves the same as `start`.

#### `flex-end`

Behaves the same as `end`.

#### `baseline`

All flex items are aligned such that their flex container baselines align. The item with the largest distance between its cross-start margin edge and its baseline is flushed with the cross-start edge of the line. Currently only supported in flexible box layout.

#### `auto`
 <Deprecated />

Equivalent to `stretch`. Not recommended, as this value doesn't exist in Web.

## Formal definition


<PropertyDefinition initialValue={<>stretch</>} appliesTo={<>flex/grid/linear containers</>} inherited="no" animatable="no" />

## Formal syntax

```
align-items = stretch | center | start | end | flex-start | flex-end | baseline | auto
```

## Differences from web

[mdn: align-items](https://developer.mozilla.org/en/docs/Web/CSS/align-items)

1. `normal`, `self-start` and `self-end` are not supported. Initial value is `stretch`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.align-items`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-items](https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-items)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/align-self.md
---

<APISummary />

## Introduction

In flex and [linear](/guide/ui/layout/linear-layout.md) layout, `align-self` will align the elements in the current container on the **cross axis**. In grid layout, `align-self` controls the alignment of child elements along the **block axis** within their grid area, and `align-self` overrides the existing value of [`align-items`](/api/css/properties/align-items.md).

For flexible box layout, if any child element's cross-axis [`margin`](/api/css/properties/margin.md) is set to auto, `align-self` will be ignored.

:::info
For grid layout, Lynx doesn't support `writing-mode`, so the block axis is the vertical axis.
:::

## Examples

**This is an example below:  css-api**

**Entry:** `src/align-self`
**Bundle:** `dist/align-self.lynx.bundle`

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

const AlignSelf = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const itemStyle = {
    width: "50px",
    height: "50px",
    margin: "5px",
    backgroundColor: "#4e98f4",
    color: "#ffffff",
    textAlign: "center" as const,
    lineHeight: "50px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view style={{ width: "100%", height: "100%", flexDirection: "column" }}>
          <text className="title">align-self: stretch;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "stretch" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>

          <text className="title">align-self: center;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "flex-start" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "center" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>

          <text className="title">align-self: flex-start;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "flex-start" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>

          <text className="title">align-self: flex-end;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "flex-end" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<AlignSelf />);

```



## Syntax

### Values

#### `auto`

**Default value**. Aligns according to the parent's [`align-items`](/api/css/properties/align-items.md) value.

#### `stretch`

If items are smaller than the container in the **cross-axis** direction (block axis in [grid](/guide/ui/layout/grid-layout.md) layout), items with unspecified dimensions (height/width) or set to `auto` will be stretched to match the height of the row or width of the column. These items still maintain their aspect ratio constraints.

#### `center`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, the item is centered along the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, the item is centered along the block axis within its grid area.

#### `start`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, the item is aligned at the start of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, the item is aligned with the start edge of its grid area along the block axis.

#### `end`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, the item is aligned at the end of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, the item is aligned with the end edge of its grid area along the block axis.

#### `flex-start`

Behaves the same as `start`.

#### `flex-end`

Behaves the same as `end`.

#### `baseline`

The item participates in baseline alignment. Currently only supported in flexible box layout.

## Formal definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>flex/grid/linear items</>} inherited="no" animatable="no" />

## Formal syntax

```
align-self = auto | center | start | end | flex-start | flex-end | baseline | stretch
```

## Differences from web

[mdn: align-self](https://developer.mozilla.org/en/docs/Web/CSS/align-self)

1. `normal`, `self-start` and `self-end` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.align-self`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-self](https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-self)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-delay.md
---

# animation-delay

<APISummary />

## Introduction

`animation-delay` property specifies the delay before the animation starts playing.

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-delay`
**Bundle:** `dist/animation-delay.lynx.bundle`

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

const AnimationDelay = () => {
  const delaySecondsProps = ["0s", "1s", "2s", "3s", "4s"];
  const delayMilliSecondsProps = ["0ms", "1000ms", "2000ms", "3000ms", "4000ms"];

  const containerStyle = {
    height: "200rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (delay: string, unit: string = "s") => ({
    animation: `rotateZ-ani 2s ease ${delay}${unit} infinite alternate both running`,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo : delay s</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">delay</text>
        <view className="fd-row" style={containerStyle}>
          {delaySecondsProps.map((item, index) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(index.toString())} className="ani-size mg5 mgl15 mgt15" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <text className="h1">keyframes animation demo : delay ms</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">delay</text>
        <view className="fd-row" style={containerStyle}>
          {delayMilliSecondsProps.map((item, index) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view
                flatten={false}
                style={getAnimationStyle(index.toString(), "ms")}
                className="ani-size mg5 mgl15 mgt15"
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationDelay />);

```



## Syntax

```css
animation-delay: 3s;
animation-delay: 2s, 4ms;
```

## Caution

:::caution

- Lynx defaults to requiring **units** for `duration` and `delay`. Writing without units may result in undefined behavior.

:::

## Formal definition


<PropertyDefinition initialValue={<>0s</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
/* default value: 0s */
animation-delay: <time>;
```

## See Also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-delay`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-delay](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-delay)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-direction.md
---

# animation-direction

<APISummary />

## Introduction

`animation-direction` property specifies whether the animation should play in reverse.

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-direction`
**Bundle:** `dist/animation-direction.lynx.bundle`

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

const AnimationDirection = () => {
  const directionProperties = ["normal", "reverse", "alternate", "alternate-reverse"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "750rpx",
  };

  const getAnimationStyle = (direction: string) => ({
    animation: `ani 1.5s ease 0s infinite ${direction} forwards running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: direction</text>
      <view className="sep"></view>

      {directionProperties.map(item => (
        <>
          <view className="fd-col group pd5" key={item}>
            <text className="button h2">direction: {item}</text>
            <view className="fd-row" style={containerStyle}>
              <view style={columnStyle} className="fd-col mg5">
                <text className="h4">direction: {item}</text>
                <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
              </view>
            </view>
          </view>
          <view className="sep"></view>
        </>
      ))}
    </scroll-view>
  );
};

root.render(<AnimationDirection />);

```



## Syntax

```css
animation-direction: normal
animation-direction: reverse
animation-direction: alternate
animation-direction: alternate-reverse
animation-direction: normal, reverse
animation-direction: alternate, reverse, normal

```

### Values

#### normal

The animation plays forward in each cycle. In other words, each animation cycle ends and resets to the starting point to begin again. This is the default behavior.

#### alternate

The animation alternates between running forwards and backwards. When running backwards, the animation steps backward and timing functions are also reversed. For example, ease-in becomes ease-out when reversed.

#### reverse

The animation runs backwards, playing from end to start.

#### alternate-reverse

The animation runs backwards on the first iteration, then forwards on the next, and continues alternating.

## Formal definition


<PropertyDefinition initialValue={<>normal</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
/*default value: normal*/
animation-direction: normal | reverse | alternate | alternate-reverse;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-direction`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-direction](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-direction)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-duration.md
---

# animation-duration

<APISummary />

## Introduction

`animation-duration` property specifies the length of time that an animation should take to complete one cycle.

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-duration`
**Bundle:** `dist/animation-duration.lynx.bundle`

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

const AnimationDuration = () => {
  const durationSecondsProps = ["0s", "1s", "2s", "3s", "4s"];
  const durationMilliSecondsProps = ["0ms", "1000ms", "2000ms", "3000ms", "4000ms"];

  const containerStyle = {
    height: "200rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (duration: string) => ({
    animation: `rotateZ-ani ${duration} ease 0s infinite alternate both running`,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">Animation Duration Demo (seconds)</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">Duration</text>
        <view className="fd-row" style={containerStyle}>
          {durationSecondsProps.map((item) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <text className="h1">Animation Duration Demo (milliseconds)</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">Duration</text>
        <view className="fd-row" style={containerStyle}>
          {durationMilliSecondsProps.map((item) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationDuration />);

```



## Syntax

```css
/* Single animation */
animation-duration: 6s
animation-duration: 120ms

/* Multiple animations */
animation-duration: 1s, 15s
animation-duration: 10s, 30s, 230ms
```

## Caution

:::caution

- Lynx defaults to requiring **units** for `duration` and `delay`. Writing without units may result in undefined behavior.

:::

## Formal definition


<PropertyDefinition initialValue={<>0s</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
/* default value: 0s */
animation-duration: <time>;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-duration`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-duration](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-duration)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-fill-mode.md
---

# animation-fill-mode

<APISummary />

## Introduction

`animation-fill-mode` property sets how a CSS animation applies styles to its target before and after its execution.

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-fill-mode`
**Bundle:** `dist/animation-fill-mode.lynx.bundle`

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

const AnimationFillMode = () => {
  const noneProperties = ["none"];
  const forwardsProperties = ["forwards"];
  const backwardsProperties = ["backwards"];
  const bothProperties = ["both"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "350px",
  };

  const getAnimationStyle = (fillMode: string) => ({
    animation: `ani 3s ease 2s 1 normal ${fillMode} running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: fillmode</text>
      <text className="h4">From--&gt; transform: translateX(50px);background-color: blue;</text>
      <text className="h4">To--&gt; transform: translateX(200px);background-color: red;</text>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">none</text>
        <view className="fd-row" style={containerStyle}>
          {noneProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">forwards</text>
        <view className="fd-row" style={containerStyle}>
          {forwardsProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">backwards</text>
        <view className="fd-row" style={containerStyle}>
          {backwardsProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">both</text>
        <view className="fd-row" style={containerStyle}>
          {bothProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationFillMode />);

```



## Syntax

```css
/* Single animation */
animation-fill-mode: none;
animation-fill-mode: forwards;
animation-fill-mode: backwards;
animation-fill-mode: both;

/* Multiple animations */
animation-fill-mode: none, backwards;
animation-fill-mode: both, forwards, none;
```

### Values

#### none

**Default value**. The animation will not apply any styles to the target when it's not executing. The element will display using the CSS rules that have already been applied to it. This is the default value.

#### forwards

The target will retain the computed values set by the last keyframe encountered during execution. The last keyframe depends on the values of [animation-direction](/api/css/properties/animation-direction.md) and [animation-iteration-count](/api/css/properties/animation-iteration-count.md):

| animation-direction | animation-iteration-count | last keyframe encountered |
| ------------------- | ------------------------- | ------------------------- |
| normal              | even or odd               | 100% or to                |
| reverse             | even or odd               | 0% or from                |
| alternate           | even                      | 0% or from                |
| alternate           | odd                       | 100% or to                |
| alternate-reverse   | even                      | 100% or to                |
| alternate-reverse   | odd                       | 0% or from                |

#### backwards

The animation will apply the values defined in the first keyframe at the start of the animation. The first keyframe depends on the value of [animation-direction](/api/css/properties/animation-direction.md):

| animation-direction          | first relevant keyframe |
| ---------------------------- | ----------------------- |
| normal or alternate          | 0% or from              |
| reverse or alternate-reverse | 100% or to              |

#### both

The animation will follow both the forwards and backwards rules, applying the keyframe values both before and after the animation.

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
/*none*/
animation-fill-mode: none | forwards | backwards | both;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-fill-mode`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-fill-mode](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-fill-mode)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-iteration-count.md
---

# animation-iteration-count

<APISummary />

## Introduction

`animation-iteration-count` property specifies the number of times an animation should be played.

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-iteration-count`
**Bundle:** `dist/animation-iteration-count.lynx.bundle`

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

const AnimationIterationCount = () => {
  const iteration1Properties = ["1"];
  const iteration3Properties = ["3"];
  const iterationInfiniteProperties = ["infinite"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (count: string) => ({
    animation: `ani 1.5s ease 0s ${count} normal forwards running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: iteration-count</text>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">iteration-count: 1</text>
        <view className="fd-row" style={containerStyle}>
          {iteration1Properties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4">iteration-count:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">iteration-count: 3</text>
        <view className="fd-row" style={containerStyle}>
          {iteration3Properties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4">iteration-count:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">iteration-count: infinite</text>
        <view className="fd-row" style={containerStyle}>
          {iterationInfiniteProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4">iteration-count:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationIterationCount />);

```



## Syntax

```css
animation-iteration-count: infinite;

animation-iteration-count: 3;

animation-iteration-count: 2, 0, infinite;
```

### Values

#### infinite

The animation will repeat forever.

#### `<number>`

The number of times the animation should repeat. Can be a non-integer value. A value of 0 will cause the animation to have no effect.

::: info
When animation-iteration-count is 0, Lynx will treat it as an animation with duration 0, and its lifetime will continue as usual. This differs from standard CSS animations where it would be treated as if the animation didn't work at all.
:::

## Formal definition


<PropertyDefinition initialValue={<>1</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
/*default value: 1*/
animation-iteration-count: <number> | infinite;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-iteration-count`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-iteration-count](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-iteration-count)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-name.md
---

# animation-name

<APISummary />

## Introduction

`animation-name` property specifies a list of animations to apply to an element. Each name refers to an animation sequence defined by [@keyframes](https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes).

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-name`
**Bundle:** `dist/animation-name.lynx.bundle`

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

const Keyframes = () => {
  const [flag, setFlag] = useState(true);

  const transProperties = ["translateX", "translateY", "translateXY"];
  const rotateProperties = ["rotateZ", "rotateX", "rotateY"];
  const scaleProperties = ["scaleX", "scaleY", "scaleXY"];
  const flipProperties = ["flipX", "flipY", "flipXY"];
  const otherProperties = ["background-color", "opacity"];

  const heightStyle = {
    height: "200rpx",
  };

  const widthStyle = {
    width: "250rpx",
  };

  const rotateHeightStyle = {
    height: "150rpx",
  };

  const scaleImageStyle = {
    marginLeft: "15px",
    marginTop: "30px",
  };

  const otherStyle = {
    marginLeft: "15px",
    marginTop: "15px",
  };

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">translate animation</text>
        <view className="fd-row" style={heightStyle}>
          {transProperties.map((item, index) => (
            <view style={widthStyle} key={`trans-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running` }}
                className="ani-size mg5 mgl15 mgt15"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">rotate animation</text>
        <view className="fd-row" style={rotateHeightStyle}>
          {rotateProperties.map((item, index) => (
            <view style={widthStyle} key={`rotate-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running` }}
                className="ani-size mg5 mgl15 mgt15"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">scale animation</text>
        <view className="fd-row" style={heightStyle}>
          {scaleProperties.map((item, index) => (
            <view style={widthStyle} key={`scale-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running`, ...scaleImageStyle }}
                className="ani-size"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">flip animation</text>
        <view className="fd-row" style={heightStyle}>
          {flipProperties.map((item, index) => (
            <view style={widthStyle} key={`flip-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running` }}
                className="ani-size mg5 mgl15 mgt15"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">bg-color opacity animation</text>
        <view className="fd-row" style={heightStyle}>
          {otherProperties.map((item, index) => (
            <view style={widthStyle} key={`other-${index}`} className="fd-col mg5">
              <text className="h4 mgl15">{item}</text>
              <view className="base"></view>
              <view
                style={{
                  animation: `${item}-ani 2s ease 0s infinite alternate both ${flag ? "running" : "paused"}`,
                  ...otherStyle,
                }}
                className="ani-size"
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<Keyframes />);

```



## Syntax

```css
/* Single animation */
animation-name: none;
animation-name: test_05;
animation-name: -specific;
animation-name: sliding-vertically;

/* Multiple animations */
animation-name: test1, animation4;
animation-name:
  none,
  -moz-specific,
  sliding;
```

::: info
Animation names are case-sensitive. The identifier must follow these naming rules, otherwise it may be treated as invalid.
:::

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
animation-name: <string>;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-name`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-name](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-name)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-play-state.md
---

# animation-play-state

<APISummary />

## Introduction

`animation-play-state` property specifies whether an animation is running or paused. When resuming a paused animation, it will continue from where it was paused rather than starting from the beginning of the animation sequence.

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-play-state`
**Bundle:** `dist/animation-play-state.lynx.bundle`

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

const AnimationPlayState = () => {
  const [playState, setPlayState] = useState(true);

  const degProperties = ["90deg", "180deg", "270deg"];
  const radProperties = ["1rad", "2rad", "3rad"];
  const turnProperties = ["0.25turn", "0.5turn", "0.75turn"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (index: number, playState: boolean) => ({
    animation: `deg-${index} 2s ease 0s infinite alternate both ${playState ? "running" : "paused"}` as const,
  });

  return (
    <view>
      <scroll-view scroll-orientation="vertical" className="fd-col container">
        <text className="h1" bindtap={() => setPlayState(!playState)}>Click to start animation</text>
        <text className="h1">Animation Play State Demo: Deg, Rad, Turn</text>
        <view className="sep"></view>

        <view className="fd-col group pd5">
          <text className="button h2">deg</text>
          <view className="fd-row" style={containerStyle}>
            {degProperties.map((item, index) => (
              <view style={columnStyle} className="fd-col mg5" key={item}>
                <text className="h4 mgl15">{item}</text>
                <view flatten={false} style={getAnimationStyle(index, playState)} className="ani-size mg5" />
              </view>
            ))}
          </view>
        </view>
        <view className="sep"></view>

        <view className="fd-col group pd5">
          <text className="button h2">rad</text>
          <view className="fd-row" style={containerStyle}>
            {radProperties.map((item, index) => (
              <view style={columnStyle} className="fd-col mg5" key={item}>
                <text className="h4 mgl15">{item}</text>
                <view flatten={false} style={getAnimationStyle(index, playState)} className="ani-size mg5" />
              </view>
            ))}
          </view>
        </view>
        <view className="sep"></view>

        <view className="fd-col group pd5">
          <text className="button h2">turn</text>
          <view className="fd-row" style={containerStyle}>
            {turnProperties.map((item, index) => (
              <view style={columnStyle} className="fd-col mg5" key={item}>
                <text className="h4 mgl15">{item}</text>
                <view flatten={false} style={getAnimationStyle(index, playState)} className="ani-size mg5" />
              </view>
            ))}
          </view>
        </view>
        <view className="sep"></view>
      </scroll-view>
    </view>
  );
};

root.render(<AnimationPlayState />);

```



## Syntax

```css
/* Single animation */
animation-play-state: running;
animation-play-state: paused;

/* Multiple animations */
animation-play-state: paused, running, running;
```

## Formal definition


<PropertyDefinition initialValue={<>running</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
/*default value:running*/
animation-play-state: running | paused;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-play-state`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-play-state](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-play-state)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-timing-function.md
---

# animation-timing-function

<APISummary />

## Introduction

`animation-timing-function` property specifies how an animation progresses through each cycle. It can accept one or more [timing functions](https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function).

## Examples

**This is an example below:  css-api**

**Entry:** `src/animation-timing-function`
**Bundle:** `dist/animation-timing-function.lynx.bundle`

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

const AnimationTimingFunction = () => {
  const timingFunctions = ["linear", "ease", "ease-in", "ease-out", "ease-in-out"];

  const columnStyle = {
    width: "500rpx",
  };

  const getAnimationStyle = (timingFunction: string) => ({
    animation: `ani 3s ${timingFunction} 0s infinite normal forwards running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: time functions</text>
      <view className="sep"></view>

      {timingFunctions.map(item => (
        <>
          <view className="fd-col group pd5" key={item}>
            <view style={columnStyle} className="fd-col mg5">
              <text className="h4">time functions:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          </view>
          <view className="sep"></view>
        </>
      ))}
    </scroll-view>
  );
};

root.render(<AnimationTimingFunction />);

```



## Syntax

```css
/* Keyword values */
animation-timing-function: ease;
animation-timing-function: ease-in;
animation-timing-function: ease-out;
animation-timing-function: ease-in-out;
animation-timing-function: linear;

/* Function values */
animation-timing-function: cubic-bezier(0.1, 0.7, 1, 0.1);
animation-timing-function: steps(4, end);
animation-timing-function: frames(10);

/* Multiple animations */
animation-timing-function: ease, steps(5, end), cubic-bezier(0.1, 0.7, 1, 0.1);
```

## Formal definition


<PropertyDefinition initialValue={<>linear</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
/*default value: linear*/
animation-timing-function: linear | ease | ease-in | ease-out | ease-in-out |
  <timing-function>;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-timing-function`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-timing-function](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-timing-function)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation.md
---

# animation

<APISummary />

## Introduction

The animation property is a shorthand property for [animation-name](/api/css/properties/animation-name.md), [animation-duration](/api/css/properties/animation-duration.md), [animation-timing-function](/api/css/properties/animation-timing-function.md), [animation-delay](/api/css/properties/animation-delay.md), [animation-iteration-count](/api/css/properties/animation-iteration-count.md), [animation-direction](/api/css/properties/animation-direction.md), [animation-fill-mode](/api/css/properties/animation-fill-mode.md), and [animation-play-state](/api/css/properties/animation-play-state.md).

## Examples

**This is an example below:  css-api**

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

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

const Keyframes = () => {
  const [flag, setFlag] = useState(true);

  const transProperties = ["translateX", "translateY", "translateXY"];
  const rotateProperties = ["rotateZ", "rotateX", "rotateY"];
  const scaleProperties = ["scaleX", "scaleY", "scaleXY"];
  const flipProperties = ["flipX", "flipY", "flipXY"];
  const otherProperties = ["background-color", "opacity"];

  const containerHeightStyle = {
    height: "200rpx",
  };

  const columnWidthStyle = {
    width: "250rpx",
  };

  const rotateHeightStyle = {
    height: "150rpx",
  };

  const scaleImageStyle = {
    marginLeft: "15px",
    marginTop: "30px",
  };

  const otherStyle = {
    marginLeft: "15px",
    marginTop: "15px",
  };

  const getAnimationStyle = (name: string) => ({
    animation: `${name}-ani 2s ease 0s infinite alternate both running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">translate animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {transProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`trans-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">rotate animation</text>
        <view className="fd-row" style={rotateHeightStyle}>
          {rotateProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`rotate-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">scale animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {scaleProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`scale-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={{ ...getAnimationStyle(item), ...scaleImageStyle }} className="ani-size" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">flip animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {flipProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`flip-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">bg-color opacity animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {otherProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`other-${index}`} className="fd-col mg5">
              <text className="h4 mgl15">{item}</text>
              <view className="base"></view>
              <view
                style={{
                  animation: `${item}-ani 2s ease 0s infinite alternate both ${flag ? "running" : "paused"}`,
                  ...otherStyle,
                }}
                className="ani-size"
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<Keyframes />);

```



## Syntax

```css
/* @keyframes name | duration | timing-function | delay |
   iteration-count | direction | fill-mode | play-state*/
animation: slidein 3s ease-in 1s 2 reverse both paused;

/* @keyframes name | duration | timing-function | delay */
animation: slidein 3s linear 1s;

/* @keyframes name | duration */
animation: slidein 3s;

/* Multiple animations */
animation:
  slidein 3s ease-in 1s 2 reverse both paused,
  ani_scale 3s linear 1s;
```

## Caution

:::caution

- When writing CSS `@keyframes`, it is recommended not to omit the values for the `0%` (or `from`) stage and `100%` (or `to`) stage. If the start and end stage values are not specified, we will use the node's current property value. Due to system limitations, the transform property on Android systems may have issues.

:::

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    animation-name: none
    <br />
    animation-duration: 0s
    <br />
    animation-timing-function: ease
    <br />
    animation-delay: 0s
    <br />
    animation-iteration-count: 1<br />
    animation-direction: normal
    <br />
    animation-fill-mode: none
    <br />
    animation-play-state: running
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  animatable="no"
/>

## Formal syntax

Animation can specify multiple sets of animations. Properties within each set of animations are separated by spaces, and sets of animations are separated by commas.

```
animation: <animation-name> || <animation-duration> ||
  <animation-timing-function> || <animation-delay> ||
  <animation-iteration-count> || <animation-direction> || <animation-fill-mode>
  || <animation-play-state>;
```

## Animation events

- [Animation Event](/api/lynx-api/event/animation-event.md)

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/aspect-ratio.md
---

# aspect-ratio

<APISummary />

## Introduction

The `aspect-ratio` CSS property sets a preferred aspect-ratio for the box, which will be used in the calculation of auto sizes and some other layout functions.

## Examples

**This is an example below:  css-api**

**Entry:** `src/aspect-ratio`
**Bundle:** `dist/aspect-ratio.lynx.bundle`

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

const AspectRatio = () => {
  const textStyle = {
    width: "50px",
    aspectRatio: "1/4",
    backgroundColor: "red",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text style={textStyle}>test</text>
      </view>
    </scroll-view>
  );
};

root.render(<AspectRatio />);

```



## Syntax

```css
aspect-ratio: 1 / 1;
aspect-ratio: 16 / 9;
aspect-ratio: 0.5;
```

### Values

#### `<ratio>`

The box's preferred aspect-ratio is the ratio of `width` to `height`. If the height and preceding slash are omitted, height defaults to 1. Size calculations involving aspect-ratio use the dimensions of the box specified by [`box-sizing`](/api/css/properties/box-sizing.md).

:::info
The `<ratio>` CSS data type represents a ratio between two numbers. It consists of:

- A positive [`<number>`](/api/css/data-type/number.md) value
- Followed by a forward slash ('/', Unicode U+002F SOLIDUS)
- Followed by a second positive `<number>` value
- Alternatively, a single positive `<number>` is allowed as a value
  :::

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    has no preferred <code>aspect ratio</code>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
/>

## Formal syntax

```css
aspect-ratio = <number [0,∞]> [ / <number [0,∞]> ]
```

## Difference with the web

[mdn: aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio)

1. `auto` is not supported, one has no preferred `aspect-ratio` by default.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.aspect-ratio`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/aspect-ratio](https://developer.mozilla.org/zh-CN/docs/Web/CSS/aspect-ratio)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.2 | - |
| iOS | 1.2 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.2 | - |
| Clay iOS | 1.2 | - |
| Clay macOS | 1.2 | - |
| Clay Windows | 1.2 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-clip.md
---

<APISummary />

## Introduction

The `background-clip` CSS property sets whether an element's background extends underneath its border box, padding box, or content box.

## Examples

**This is an example below:  css-api**

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

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

const BackgroundClip = () => {
  const scrollViewStyle = {
    flexDirection: "column" as const,
    height: "2000px",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="shared border-box"></text>
        <text className="shared padding-box"></text>
        <text className="shared content-box"></text>
        <text className="shared border-box radius"></text>
        <text className="shared padding-box radius"></text>
        <text className="shared content-box radius"></text>
        <text className="shared border-box radius2"></text>
        <text className="shared padding-box radius2"></text>
        <text className="shared content-box radius2"></text>
        <view className="container"></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundClip />);

```



## Syntax

```css
background-clip: border-box;
background-clip: padding-box;
background-clip: content-box;
background-clip: border-area;

// multiple clip
background-clip: border-box, content-box, padding-box, border-area;
```

### Values

- **`border-box`** <br />
  The background extends to the outside edge of the border (but underneath the border in z-ordering).

- **`padding-box`** <br />
  The background extends to the outside edge of the padding. No background is drawn beneath the border

- **`content-box`**
  The background is painted within (clipped to) the content box.

- **`border-area`**
  The background is painted within (clipped to) the area painted by the border, taking [`border-width`](/api/css/properties/border-width.md) into account.

## Note

If the length of `background-clip` is less than [`background-image`](/api/css/properties/background-image.md), the first clip value will effect on all remained [`background-image`](/api/css/properties/background-image.md).

## Formal definition


<PropertyDefinition initialValue={<>border-box</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
<background-clip> = <box> | border-area

where

<box> = border-box | padding-box | content-box

```

## Difference between web

- Only support `border-box`、`padding-box`、`content-box` 、 `border-area` <br />

- `background-clip:text` is not support, and if want show text with gradient color, just set `color: <gradient>`.

- `border-area` doesn't take `border-style` into account.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-clip`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-clip](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-clip)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-color.md
---

<APISummary />

## Introduction

The `background-color` CSS property sets the background color of an element.

## Examples

**This is an example below:  css-api**

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

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

const BackgroundColor = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="container text1"></text>
        <text className="container text2"></text>
        <text className="container text3"></text>
        <text className="container text4"></text>
        <text className="container text5"></text>
        <text className="container text6"></text>
        <text className="container text7"></text>
        <text className="container text8"></text>
        <text className="container text9"></text>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundColor />);

```



## Syntax

```css
/* Keyword values */
background-color: red;

/* Hexadecimal value */
background-color: #bbff00;

/* RGB value */
background-color: rgb(255, 255, 128);

/* HSLA value */
background-color: hsla(50, 33%, 25%, 0.75);
```

### Values

- [`<color>`](/api/css/data-type/color.md) <br />
  The uniform color of the background.

- Default value **transparent** <br />

## Formal definition


<PropertyDefinition initialValue={<>transparent</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal Syntax

```
<bg-color> = <rgb()> | <rgba()> | <hsl()> | <hsla()> | <hex-color> | <named-color>
```

## Difference between web

- Not support special keywords like `currentcolor`
- Not support global keywords like `inherit`、`initial`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-image.md
---

<APISummary />

## Introduction

The `background-image`
 CSS property sets one or more background images on an element. <br />

The background images are drawn on stacking context layers on top of each other. The first layer specified is drawn as if it is closest to the user. <br />

The [border](/api/css/properties/border.md)
 of the element are then drawn on top of them, and the [`background-color`](/api/css/properties/background-color.md)
 is drawn beneath them. How the images are drawn relative to the box and its borders is defined by the [`background-clip`](/api/css/properties/background-clip.md)
 and [`background-origin`](/api/css/properties/background-origin.md)
 CSS properties. <br />

## Examples

**This is an example below:  css-api**

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

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

import Flower from "../../resource/bg_flower.gif?inline";
import LynxIcon from "../../resource/lynx.png?inline";

const BackgroundImage = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    image1: {
      backgroundImage: `url(${Flower})`,
    },
    image2: {
      backgroundImage: `url(${LynxIcon}), url(${Flower})`,
    },
    gradient1: {
      width: "50%",
      backgroundImage: "linear-gradient(black, green)",
    },
    gradient2: {
      width: "50%",
      backgroundImage: "linear-gradient(green 40%, yellow 30%, blue 70%)",
    },
    gradient3: {
      width: "50%",
      backgroundImage: "linear-gradient(green 40%, yellow 40%, blue 70%)",
    },
    conic: {
      width: "50%",
      height: "100%",
      backgroundImage: "conic-gradient(from 180deg at 50% 50%, red, blue, red)",
    },
    radial1: {
      width: "50%",
      backgroundImage: "radial-gradient(red, green)",
    },
    radial2: {
      width: "50%",
      backgroundImage: "radial-gradient(circle at 100%, #333, #333 50%, #eee 75%, #333 75%)",
    },
    radial3: {
      width: "100%",
      height: "100%",
      backgroundImage: "radial-gradient(ellipse closest-side at 0% 0%, #eabf8a 0%, #c5a35f 100%)",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container" style={containerStyles.image1}></view>
        <view className="container" style={containerStyles.image2}></view>
        <view className="container">
          <view style={containerStyles.gradient1}></view>
          <view style={containerStyles.conic}></view>
        </view>
        <view className="container">
          <view style={containerStyles.gradient2} />
          <view style={containerStyles.gradient3} />
        </view>
        <view className="container">
          <view style={containerStyles.radial1} />
          <view style={containerStyles.radial2} />
        </view>
        <view className="container">
          <view style={containerStyles.radial3} />
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundImage />);

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

```



## Syntax

```css
background-image: linear-gradient(
    to bottom,
    rgba(255, 255, 0, 0.5),
    rgba(0, 0, 255, 0.5)
  ),
  url('https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/catfront.png');
```

### Values

Each background image is specified either as the keyword `none`
 or as an `<image>`
 value. <br />

- `none`
  Is a keyword denoting the absence of images.

- `<image>`
  Is an `<image>` denoting the image to display. There can be several of them, separated by commas.
  The supported image formats for background-image are the same as those for image, including jpg, png, gif, webp, etc. Refer to [Supported Image Formats](/api/elements/built-in/image.md#compatibility)

## Events

| Name        | Type     | Essential | Description     |
| ----------- | -------- | --------- | --------------- |
| bindbgload  | function | NO        | Loading succeed |
| bindbgerror | function | NO        | Loading failed  |

## Related properties of view

| Name                             | Type    | Default | Example | Essential | Description                                                                                                                                                                                     |
| -------------------------------- | ------- | ------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <AndroidOnly /> skip-redirection | boolean | false   | true    | NO        | It only needs to be set when the background-image uses `<url()>` and is a CDN image. When set to true, the logic of container redirection can be skipped to optimize the related time-consuming |

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
background-image = <bg-image>#

<bg-image> = none | <image>

<image> = <url()> | <gradient>

<url()> = url(<string>)

<gradient> = <linear-gradient()> | <radial-gradient()> | <conic-gradient()>

<linear-gradient()> =
  linear-gradient( [ <angle> | to <side-or-corner> ]? , <color-stop-list> )

<radial-gradient()> =
  radial-gradient( [ <ending-shape> || <size> ]? [ at <position> ]? , <color-stop-list> )

<conic-gradient()> =
  conic-gradient( [ from [ <angle> | <zero> ] ]? [ at <position> ]? , <color-stop-list> )

<side-or-corner> =
  [ left | right ] || [ top | bottom ]

<ending-shape> =
  circle | ellipse

<size> =
  closest-side       |
  farthest-side      |
  closest-corner     |
  farthest-corner    |
  <length>           |
  <length-percentage>{2}

<position> =
  [ left | center | right ] || [ top | center | bottom ]                            |
  [ left | center | right | <length-percentage> ]
    [ top | center | bottom | <length-percentage> ]?                                |
  [ [ left | right ] <length-percentage> ] &&
    [ [ top | bottom ] <length-percentage> ]

<color-stop-list> = <linear-color-stop> ( ',' <linear-color-stop> )*

<linear-color-stop> = <color>

<length-percentage> = <length> | <percentage>

```

## Difference between web

- `<image>`
  Only support `<url()>` and `<gradient>`.

- `<gradient>`
  Support `linear-gradient`, `radial-gradient`, and `conic-gradient`(since version 3.6).

- `<linear-color-stop>`
  Not support [`linear-color-hint`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-image#linear-color-hint)

  Not support [`color-interpolation-method`](https://www.w3.org/TR/css-images-4/#linear-gradients)

  Not support [`<length>`](/api/css/data-type/length.md) value for position

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-image`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-image](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-image)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-origin.md
---

<APISummary />

## Introduction

The `background-origin` CSS property sets the background's origin: from the border start, inside the border, or inside the padding.

## Examples

**This is an example below:  css-api**

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

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

const BackgroundOrigin = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
    },
    style3: {
      backgroundOrigin: "border-box" as const,
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundOrigin />);

```



## Syntax

```css
background-origin: border-box
background-origin: padding-box
background-origin: content-box
// multiple bg-origin
background-origin: content-box, padding-box;
```

### Values

- Default value **padding-box** <br />
  The background is positioned relative to the border box.

- **border-box** <br />
  The background is positioned relative to the padding box.

- **content-box** <br />
  The background is positioned relative to the content box.

## Formal definition


<PropertyDefinition initialValue={<>padding-box</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
border-box | padding-box | content-box
```

## Difference between web

- Not support `inherit`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-origin`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-origin](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-origin)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-position.md
---

## Introduction

The `background-position` CSS property sets the initial position for each background image. The position is relative to the position layer set by [`background-origin`](/api/css/properties/background-origin.md).

# Examples

<APISummary />

**This is an example below:  css-api**

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

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

const BackgroundPosition = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
      backgroundPosition: "50% 50%",
    },
    style3: {
      backgroundOrigin: "border-box" as const,
      backgroundPosition: "30px 40px",
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
      backgroundPosition: "50% 40px, right bottom",
    },
    style5: {
      backgroundOrigin: "padding-box" as const,
      backgroundSize: "auto 100%",
      backgroundRepeat: "no-repeat" as const,
      backgroundPosition: "-13px -20px",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
        <view className="container image1" style={containerStyles.style5}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundPosition />);

```



## Syntax

```css
/* Keyword values */
background-position: top;
background-position: bottom;
background-position: left;
background-position: right;
background-position: center;

/* <percentage> values */
background-position: 25% 75%;

/* <length> values */
background-position: 0px 0px;
background-position: 1rem 2rem;
background-position: 10em 8em;

/* Multiple images */
background-position:
  0px 0px,
  center;
```

### Values

- **1-value syntax**

  - Keyword `center`, which centers the image.
  - Keyword `top`, `left`, `bottom`, `right`. This specifies an edge against which to place the item. The other dimension is then set to 50%, so the item is placed in the middle of the edge specified.
  - [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md). This specifies the X coordinate relative to the left edge, with the Y coordinate set to 50%.

- **2-value syntax**

  - One of the keyword values `top`, `left`, `bottom`, `right`. If `left` or `right` are given here, then this defines X and the other given value defines Y. If `top` or `bottom` are given, then this defines Y and the other value defines X.
  - A [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md). If the other value is left or right, then this value defines Y, relative to the top edge. If the other value is top or bottom, then this value defines X, relative to the left edge. If both values are `<length>` or `<percentage>` values, then the first defines X and the second Y.
  - Note that: If one value is `top` or `bottom`, then the other value may not be `top` or `bottom`. If one value is `left` or `right`, then the other value may not be `left` or `right`. This means, e.g., that `top` `top` and `left` `right` are not valid.

- Default value
  - `left top` or `0% 0%`

## Formal definition


<PropertyDefinition initialValue={<>0% 0%</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
[ left | center | right | top | bottom | <length-percentage> ] | [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]

<length-percentage> = <length> | <percentage>
```

## Difference between web

- Not support **Global Value** like `inherit`、`initial` and `unset`.
- Not support **Edge offsets syntax** like:

```
background-position: bottom 10px right 20px
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-position`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-position](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-position)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-repeat.md
---

<APISummary />

## Introduction

The `background-repeat` CSS property sets how background images are repeated. A background image can be repeated along the horizontal and vertical axes, or not repeated at all.

## Examples

**This is an example below:  css-api**

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

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

const BackgroundRepeat = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
      backgroundRepeat: "no-repeat" as const,
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
      backgroundPosition: "50% 50%",
      backgroundRepeat: "repeat-x" as const,
    },
    style3: {
      backgroundOrigin: "border-box" as const,
      backgroundPosition: "30px 40px",
      backgroundRepeat: "repeat" as const,
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
      backgroundPosition: "50% 40px, right bottom",
      backgroundRepeat: "repeat-y,repeat-x" as const,
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundRepeat />);

```



## Syntax

```css
background-repeat: repeat-x;
background-repeat: repeat-y;
background-repeat: repeat;
background-repeat: space;
background-repeat: round;
background-repeat: no-repeat;

background-repeat: repeat space;
background-repeat: repeat repeat;
background-repeat: round space;
background-repeat: no-repeat round;
```

### Values

- Default value **repeat** <br />
  The image is repeated as much as needed to cover the whole background image painting area. The last image will be clipped if it doesn't fit.

- no-repeat <br />
  The image is not repeated (and hence the background image painting area will not necessarily be entirely covered). The position of the non-repeated background image is defined by `background-position`(./background-position).

- repeat-x <br />
  Repeat along x-axis.

- repeat-y <br />
  Repeat along y-axis.

- space <br />
  The image is repeated as much as possible without clipping. The first and last images are pinned to either side of the element, and whitespace is distributed evenly between the images. And `background-position`(./background-position) is ignored.

- round <br />
  As the allowed space increases in size, the repeated images will stretch (leaving no gaps) until there is room (space left >= half of the image width) for another one to be added.

:::info
The rendering behavior of the `space` and `round` keywords is actually the same as that of `repeat`.
:::

## Formal definition


<PropertyDefinition initialValue={<>repeat</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
<repeat-style> = repeat-x | repeat-y | [ repeat | space | round | no-repeat ]{1,2}
```

## ## Difference between web

- Not support `inherit`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-repeat`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-repeat](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-repeat)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-size.md
---

<APISummary />

## Introduction

The `background-size` CSS property sets the size of the element's background image. The image can be left to its natural size, stretched, or constrained to fit the available space.

## Examples

**This is an example below:  css-api**

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

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

const BackgroundSize = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
      backgroundRepeat: "no-repeat" as const,
      backgroundSize: "50%",
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
      backgroundPosition: "50% 50%",
      backgroundRepeat: "repeat-x" as const,
      backgroundSize: "40px, 30px",
    },
    style3: {
      backgroundOrigin: "border-box" as const,
      backgroundPosition: "50% 50%",
      backgroundRepeat: "repeat" as const,
      backgroundSize: "cover" as const,
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
      backgroundPosition: "top left, right bottom",
      backgroundRepeat: "repeat-y,repeat-x" as const,
      backgroundSize: "50% 50%, contain",
    },
    style5: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
      backgroundRepeat: "no-repeat" as const,
      backgroundSize: "auto 200%",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
        <view className="container image1" style={containerStyles.style5}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundSize />);

```



## Syntax

```css
background-size: contain;

background-size: 50%;
background-size: 3em;

background-size: auto 1em;
background-size: 50% 25%;
```

### Values

- `cover` <br />
  Scales the image as large as possible within its container without cropping or stretching the image. If the container is larger than the image, this will result in image tiling, unless the [`background-repeat`](/api/css/properties/background-repeat.md) property is set to `no-repeat`.

- `contain` <br />
  Scales the image (while preserving its ratio) to the smallest possible size to fill the container (that is: both its height and width completely cover the container), leaving no empty space. If the proportions of the background differ from the element, the image is cropped either vertically or horizontally.

- Default value **auto** <br />
  Scales the background image in the corresponding direction such that its intrinsic proportions are maintained.

- [`<length>`](/api/css/data-type/length.md) <br />
  Stretches the image in the corresponding dimension to the specified length. Negative values are not allowed.

- [`<percentage>`](/api/css/data-type/percentage.md) <br />
  Stretches the image in the corresponding dimension to the specified percentage of the background positioning area. The background positioning area is determined by the value of [`background-origin`](/api/css/properties/background-origin.md) (by default, the padding box).

### Size Calculation

- If both components of `background-size` are specified and are not `auto`: <br />
  The background image is rendered at the specified size.

- `contain` or `cover`: <br />
  While preserving its intrinsic proportions, the image is rendered at the largest size contained within, or covering, the background positioning area. If the image has no intrinsic proportions, then it's rendered at the size of the background positioning area.

- If the background-size has one `auto` component and one `non-auto` component: <br />
  The image stretched to the specified dimension. The unspecified dimension is computed using the specified dimension and the intrinsic proportions.

## Notes

Do not use `auto` with `<gradient>`. It may cause some rendering issue in old version SDK.

## Formal definition


<PropertyDefinition initialValue={<>auto auto</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
<bg-size> = (<length-percentage> | auto){1,2} | cover | contain
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-size`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-size](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-size)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background.md
---

<APISummary />

## Introduction

The `background` shorthand CSS property sets all background style properties at once, such as [`background-clip`](/api/css/properties/background-clip.md),[`background-color`](/api/css/properties/background-color.md),[`background-image`](/api/css/properties/background-image.md),[`background-origin`](/api/css/properties/background-origin.md),[`background-position`](/api/css/properties/background-position.md),[`background-repeat`](/api/css/properties/background-repeat.md),[`background-size`](/api/css/properties/background-size.md).

## Examples

**This is an example below:  css-api**

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

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

const Background = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const container1Style = {
    backgroundOrigin: "content-box" as const,
    backgroundPosition: "left top" as const,
    backgroundRepeat: "no-repeat" as const,
  };

  const container2Style = {
    backgroundOrigin: "padding-box" as const,
    backgroundPosition: "50% 50%",
    backgroundRepeat: "repeat-x" as const,
  };

  const container3Style = {
    backgroundOrigin: "border-box" as const,
    backgroundPosition: "30px 40px",
    backgroundRepeat: "repeat" as const,
  };

  const container4Style = {
    backgroundOrigin: "content-box,border-box" as const,
    backgroundPosition: "50% 40px, right bottom",
    backgroundRepeat: "repeat-y,repeat-x" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={container1Style}></view>
        <view className="container image1" style={container2Style}></view>
        <view className="container image1" style={container3Style}></view>
        <view className="container image2" style={container4Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<Background />);

```



## Syntax

```css
/* Using a <background-color> */
background: green;

/* Using a <bg-image> and <repeat-style> */
background: url('test.jpg') repeat-y;

/* Using a <box> and <background-color> */
background: border-box red;

/* A single image, centered and scaled */
background: no-repeat center / 80% url('../img/image.png');
```

The background property is specified as one or more background layers, separated by commas.

The syntax of each layer is as follows:

- [`<bg-image>`](#bg-image)
- [`<position>`](#position)
- [`<bg-size>`](#bg-size)
- [`<repeat-style>`](#repeat-style)
- The `<bg-size>` value may only be included immediately after `<position>`, separated with the '/' character, like this: `"center/80%"`.
- The `<box>` value may be included zero, one, or two times. If included once, it sets both [`background-origin`](/api/css/properties/background-origin.md) and [`background-clip`](/api/css/properties/background-clip.md). If it is included twice, the first occurrence sets [`background-origin`](/api/css/properties/background-origin.md), and the second sets [`background-clip`](/api/css/properties/background-clip.md).

> **The [`background-color`](/api/css/properties/background-color.md) value may only be included in the last layer specified.**

## Values

#### `<box>` \{#box}

See [`background-clip`](/api/css/properties/background-clip.md) and [`background-origin`](/api/css/properties/background-origin.md)

#### `<background-color>` \{#background-color}

See [`background-color`](/api/css/properties/background-color.md)

#### `<bg-image>` \{#bg-image}

See [`background-image`](/api/css/properties/background-image.md)

#### `<position>` \{#position}

See [`background-position`](/api/css/properties/background-position.md)

#### `<repeat-style>` \{#repeat-style}

See [`background-repeat`](/api/css/properties/background-repeat.md)

#### `<bg-size>` \{#bg-size}

See [`background-size`](/api/css/properties/background-size.md)

## Note

- The background-color must be written in the last image, otherwise the parser will consider it an invalid background.
  For example: `background: red url('./a.png'), url('./b.png);'` will be ignored as an error.
  The correct way to write it should be: `background: url('./a.png'),red url('./b.png);`

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    background-image: none
    <br />
    background-position: 0% 0%
    <br />
    background-size: auto auto
    <br />
    background-repeat: repeat
    <br />
    background-origin: padding-box
    <br />
    background-clip: border-box
    <br />
    background-color: transparent
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  animatable="no"
/>

## Formal Syntax

```
[ <bg-layer> , ]* <final-bg-layer>

where

<bg-layer> = <bg-image> || <bg-position> [ / <bg-size> ]? || <repeat-style> || <box> || <box>
<final-bg-layer> = <'background-color'> || <bg-image> || <bg-position> [ / <bg-size> ]? || <repeat-style> || <attachment> || <box> || <box>

where

<bg-image> = none | <image>
<bg-position> = [ [ left | center | right | top | bottom | <length-percentage> ] | [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ] | [ center | [ left | right ] <length-percentage>? ] && [ center | [ top | bottom ] <length-percentage>? ] ]
<bg-size> = [ <length-percentage> | auto ]{1,2} | cover | contain
<repeat-style> = repeat-x | repeat-y | [ repeat | space | round | no-repeat ]{1, 2}
<box> = border-box | padding-box | content-box

where

<image> = <url> | <gradient>
<length-percentage> = <length> | <percentage>

where

<gradient> = <linear-gradient> | <radial-gradient>

```

## Difference between web

- `<bg-layer>` does not support the [`<attachment>`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background#attachment)
- `<image>` only support `<url>` and `<gradient>`
  > \_These properties are also supported in web such as `<image-set>`、`<element()>`、`<paint()>`、`<cross-fade()>` \_<br />
- `<gradient>` only support `<linear-gradient>` and `<radial-gradient>`
  > _These properties are also supported in web such as `<repeating-linear-gradient()>`,`<radial-gradient()>`,`<repeating-radial-gradient()>`,`<conic-gradient()>`_

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-color.md
---

# border-bottom-color

<APISummary />

## Introduction

Sets the bottom border color of an element. Used when you need to specify the bottom border color separately.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-bottom-color`
**Bundle:** `dist/border-bottom-color.lynx.bundle`

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

const BorderBottomColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderBottomColor />);

```



## Syntax

```css
border-bottom-color: red;

border-bottom-color: '#ff0000';
```

### Values

- [`<color>`](/api/css/data-type/color.md)

## Formal Definition


<PropertyDefinition initialValue={<>Empty</>} appliesTo={<>All elements</>} inherited="no" animatable="yes" />

## Formal Syntax

```css
border-bottom-color = <color>
<color> = <rgb()> | <rgba()> | <hsl()> | <hsla()> | <hex-color> | <named-color>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-color)
- Different default value (Web uses `currentColor`)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-left-radius.md
---

# border-bottom-left-radius

<APISummary />

## Introduction

Used to add a rounded border to the bottom-left corner. The first value sets the horizontal radius, and the second value sets the vertical radius. If the second value is omitted, it copies the first value. A value of zero results in a square corner rather than a rounded one. The percentage value of the horizontal radius is relative to the border box width, while the percentage value of the vertical radius is relative to the border box height.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-bottom-left-radius`
**Bundle:** `dist/border-bottom-left-radius.lynx.bundle`

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

const BorderBottomLeftRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomLeftRadius />);

```



## Syntax

```css
/* The corner is a circle */
/* border-bottom-left-radius: radius */
border-bottom-left-radius: 3px;

/* The corner is an ellipse */
/* border-bottom-left-radius: horizontal vertical */
border-bottom-left-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Defines the specific size of the border radius (default is `0`).

- [`<percentage>`](/api/css/data-type/percentage.md)
  Defines the border radius in percentage (horizontal radius is relative to the border box width, vertical radius is relative to the height).

## Formal Definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>All elements</>} inherited="no" animatable="no" />

## Formal Syntax

```css
border-bottom-left-radius = <length-percentage>{1,2}
<length-percentage> = <length> | <percentage>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-left-radius)
- Does not support global values (`inherit` / `initial` / `revert` / `unset`).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-left-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-left-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-left-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-right-radius.md
---

# border-bottom-right-radius

<APISummary />

## Introduction

Used to add a rounded border to the bottom-right corner. The first value sets the horizontal radius, and the second value sets the vertical radius. If the second value is omitted, it copies the first value. A value of zero results in a square corner rather than a rounded one. The percentage value of the horizontal radius is relative to the border box width, while the percentage value of the vertical radius is relative to the border box height.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-bottom-right-radius`
**Bundle:** `dist/border-bottom-right-radius.lynx.bundle`

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

const BorderBottomRightRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomRightRadius />);

```



## Syntax

```css
border-bottom-right-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Defines the specific size of the border radius (default is `0`).

- [`<percentage>`](/api/css/data-type/percentage.md)
  Defines the border radius in percentage (horizontal radius is relative to the border box width, vertical radius is relative to the height).

## Formal Definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>All elements</>} inherited="no" animatable="no" />

## Formal Syntax

```css
border-bottom-right-radius = <length-percentage>{1,2}
<length-percentage> = <length> | <percentage>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-right-radius)
- Does not support global values (`inherit` / `initial` / `revert` / `unset`).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-right-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-right-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-right-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-style.md
---

# border-bottom-style

<APISummary />

## Introduction

Sets the style type of the bottom border of an element. Used when you need to specify the bottom border style separately.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-bottom-style`
**Bundle:** `dist/border-bottom-style.lynx.bundle`

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

const BorderBottomStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-same-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-same-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-diff-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-diff-${rowIndex}-${colIndex}`}
                  className="box colorWidth1 radiusDiff"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomStyle />);

```



## Syntax

```css
border-bottom-style: dashed;
```

### Values

- `none`: No border style (border width remains unchanged)
- `hidden`: Hides the border (equivalent to `none`, used in table layouts to resolve border conflicts)
- `dotted`: Dotted border (renders as a solid line)
- `dashed`: Dashed border (renders as a solid line)
- `solid`: Solid line
- `double`: Double line (total width equals `border-width` value)
- `groove`: 3D groove effect (depends on `border-color`)
- `ridge`: 3D ridge effect (depends on `border-color`)
- `inset`: Inset effect (depends on `border-color`)
- `outset`: Outset effect (depends on `border-color`)

## Formal Definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>All elements</>} inherited="no" animatable="no" />

## Formal Syntax

```css
border-bottom-style = <line-style>
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-style)
- Different default value (Web uses `none`)
- When set to `none` or `hidden`, the border width remains unchanged (on the Web, it is set to `0`)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-width.md
---

# border-bottom-width

<APISummary />

## Introduction

Used to set the width of the bottom border.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-bottom-width`
**Bundle:** `dist/border-bottom-width.lynx.bundle`

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

const BorderBottomWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderBottomWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderBottomWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderBottomWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomWidth />);

```



## Syntax

```css
border-bottom-width: 10px;
```

### Values

- `thin`: Thin border (2px)
- `medium`: Medium border (4px)
- `thick`: Thick border (6px)
- [`<length>`](/api/css/data-type/length.md): Specific size value

## Formal Definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>All elements</>} inherited="no" animatable="yes" />

## Formal Syntax

```css
border-bottom-width = <line-width>
<line-width> = thin | medium | thick | <length>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width)
- Different specific size values (Web standard: `thin=1px, medium=3px, thick=5px`)
- Different default value (Web uses `medium`)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom.md
---

# border-bottom

<APISummary />

## Introduction

Used to set the styles related to the bottom border. This property allows setting `border-bottom-width`, `border-bottom-style`, and `border-bottom-color` in order.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-bottom`
**Bundle:** `dist/border-bottom.lynx.bundle`

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

const BorderBottom = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view key={`normal-${rowIndex}-${colIndex}`} className="box" style={{ borderBottom: borderStyle }}>
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderBottom: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottom />);

```



## Syntax

```css
/* Bottom border with thick double red lines */
border-bottom: thick double red;

/* Bottom border with thin dotted blue lines */
border-bottom: thin dotted blue;

/* Bottom border with a 10px dashed orange line */
border-bottom: 10px dashed orange;
```

### Values

Accepts the following value types in order:

- [`<line-width>`](/api/css/properties/border-bottom.md#formal-definition)

  - See [`<border-bottom-width>`](/api/css/properties/border-bottom-width.md)

- [`<line-style>`](/api/css/properties/border-bottom.md#formal-definition)

  - See [`<border-bottom-style>`](/api/css/properties/border-bottom-style.md)

- [`<color>`](/api/css/data-type/color.md)
  - See [`<border-bottom-color>`](/api/css/properties/border-bottom-color.md)

## Formal Definition


<PropertyDefinition initialValue={<>Empty</>} appliesTo={<>All elements</>} inherited="no" animatable="no" />

## Formal Syntax

```css
border-bottom =
  <line-width>  ||
  <line-style>  ||
  <color>

<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Differences from the Web

- [mdn:border-bottom](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-color.md
---

<APISummary />

## Introduction

The `border-color` shorthand CSS property sets the color ([`border-top-color`](/api/css/properties/border-top-color.md), [`border-right-color`](/api/css/properties/border-right-color.md), [`border-bottom-color`](/api/css/properties/border-bottom-color.md), [`border-left-color`](/api/css/properties/border-left-color.md)) of an element's border.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-color`
**Bundle:** `dist/border-color.lynx.bundle`

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

const BorderColor = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const colors = [
    ["red", "rgb(255,0,0) rgba(0,255,0,0.3)"],
    ["#ff0000 #00ff00ff #aabbccdd", "black orange transparent pink"],
    ["black rgb(255,255,0) #ff00ff pink", "hsl(89,43%,51%) hsla(89,43%,51%,0.3) red transparent"],
  ];

  const colors2 = [
    ["green blue", "pink rgb(0,0,255) rgba(128,0,128,0.8)"],
    ["#ff00ff #00ffffbb #2211ffaa", "blue pink"],
    ["#aab #ff00ff hsl(89,43%,20%)", "hsl(89,60%,31%) blue"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {colors.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((color, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box widthSame solid"
                  style={{ borderColor: color }}
                >
                  <text className="text">{color}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {colors2.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((color, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box widthSame styleDiff${colIndex}`}
                  style={{ borderColor: color }}
                >
                  <text className="text">{color}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {colors.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((color, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box widthDiff styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderColor: color }}
                >
                  <text className="text">{color}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderColor />);

```



## Syntax

```css
/* border-color: color; */
border-color: red;

/* border-color: vertical horizontal; */
border-color: red #f015ca;

/* border-color: top horizontal bottom; */
border-color: red yellow green;

/* border-color: top right bottom left; */
border-color: red yellow green blue;
```

### Values

The [`<color>`](/api/css/data-type/color.md) property may be specified using one, two, three, or four values.

- When one value is specified, it applies the same color to all four sides.
- When two values are specified, the first color applies to the [`border-top-color`](/api/css/properties/border-top-color.md) and [`border-bottom-color`](/api/css/properties/border-bottom-color.md), the second to the [`border-left-color`](/api/css/properties/border-left-color.md) and [`border-right-color`](/api/css/properties/border-right-color.md).
- When three values are specified, the first color applies to the [`border-top-color`](/api/css/properties/border-top-color.md), the second to the [`border-left-color`](/api/css/properties/border-left-color.md) and [`border-right-color`](/api/css/properties/border-right-color.md), the third to the [`border-bottom-color`](/api/css/properties/border-bottom-color.md).
- When four values are specified, the colors apply to the [`border-top-color`](/api/css/properties/border-top-color.md), [`border-right-color`](/api/css/properties/border-right-color.md), [`border-bottom-color`](/api/css/properties/border-bottom-color.md) and [`border-left-color`](/api/css/properties/border-left-color.md) in that order (clockwise).

## Formal definition


<PropertyDefinition initialValue={<>transparent</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

```
<color>{1, 4}
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-end-end-radius.md
---

<APISummary />

## Introduction

The `border-end-end-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-bottom-right-radius`](/api/css/properties/border-bottom-right-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-bottom-left-radius`](/api/css/properties/border-bottom-left-radius.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-end-end-radius`
**Bundle:** `dist/border-end-end-radius.lynx.bundle`

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

const BorderEndEndRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderEndEndRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderEndEndRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-end-radius: radius */
border-end-end-radius: 3px;

/* the corner is an ellipsis */
/* border-end-end-radius: horizontal vertical */
border-end-end-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-end-end-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-end-end-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-end-end-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-end-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-end-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-end-start-radius.md
---

<APISummary />

## Introduction

The `border-end-start-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-bottom-left-radius`](/api/css/properties/border-bottom-left-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-bottom-right-radius`](/api/css/properties/border-bottom-right-radius.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-end-start-radius`
**Bundle:** `dist/border-end-start-radius.lynx.bundle`

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

const BorderEndStartRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderEndStartRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderEndStartRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-start-radius: radius */
border-end-start-radius: 3px;

/* the corner is an ellipsis */
/* border-end-start-radius: horizontal vertical */
border-end-start-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition


<PropertyDefinition initialValue={<>0px</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]?
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-end-start-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-end-start-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-end-start-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-start-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-start-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-end-color.md
---

<APISummary />

## Introduction

The `border-inline-end-color` CSS property defines the color of the logical inline-end border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-right-color`](/api/css/properties/border-right-color.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-color`](/api/css/properties/border-left-color.md) property.

## Examples

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/border-color.png)

## Syntax

```css
border-inline-end-color: red;
border-inline-end-color: #ffbb00;
border-inline-end-color: rgb(255, 0, 0);
border-inline-end-color: hsla(100%, 50%, 25%, 0.75);
border-inline-end-color: currentColor;
border-inline-end-color: transparent;
```

### Values

- `transparent`

- [`<color>`](/api/css/data-type/color.md)

## Formal definition


<PropertyDefinition initialValue={<>0px</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
transparent | <color>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-end-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-color)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-end-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-end-style.md
---

<APISummary />

## Introduction

The `border-inline-end-style` CSS property defines the style of the logical inline end border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-right-style`](/api/css/properties/border-right-style.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-style`](/api/css/properties/border-left-style.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-inline-end-style`
**Bundle:** `dist/border-inline-end-style.lynx.bundle`

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

const BorderInlineEndStyle = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartStyle: "dashed",
    borderInlineEndStyle: "solid",
  } as const;

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineEndStyle />);

```



## Syntax

```css
border-inline-end-style: none;
border-inline-end-style: hidden;
border-inline-end-style: dotted;
border-inline-end-style: dashed;
border-inline-end-style: solid;
border-inline-end-style: double;
border-inline-end-style: groove;
border-inline-end-style: ridge;
border-inline-end-style: inset;
border-inline-end-style: outset;
```

### Values

- `none`

- `hidden`

- `dotted`

- `dashed`

- **default** `solid`

- `double`

- `groove`

- `ridge`

- `inset`

- `outset`

## Formal definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-end-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-style)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-end-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-end-width.md
---

<APISummary />

## Introduction

The `border-inline-end-width` CSS property defines the width of the logical inline-end border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-right-width`](/api/css/properties/border-right-width.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-width`](/api/css/properties/border-left-width.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-inline-end-width`
**Bundle:** `dist/border-inline-end-width.lynx.bundle`

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

const BorderInlineEndWidth = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartWidth: "5px",
    borderInlineEndWidth: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineEndWidth />);

```



## Syntax

```css
border-inline-end-width: thin;
border-inline-end-width: medium;
border-inline-end-width: thick;
border-inline-end-width: 10px;
```

### Values

- `thin`

- `medium`

- `thick`

- [`<length>`](/api/css/data-type/length.md)

## Formal definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
thin | medium | thick | <length>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-end-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-width)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-end-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-start-color.md
---

<APISummary />

## Introduction

The `border-inline-start-color` CSS property defines the color of the logical inline start border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-left-color`](/api/css/properties/border-left-color.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-color`](/api/css/properties/border-right-color.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-inline-start-color`
**Bundle:** `dist/border-inline-start-color.lynx.bundle`

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

const BorderInlineStartColor = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartColor: "blue",
    borderInlineEndColor: "yellow",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineStartColor />);

```



## Syntax

```css
border-inline-start-color: red;
border-inline-start-color: #ffbb00;
border-inline-start-color: rgb(255, 0, 0);
border-inline-start-color: hsla(100%, 50%, 25%, 0.75);
border-inline-start-color: currentColor;
border-inline-start-color: transparent;
```

### Values

- `transparent`

- [`<color>`](/api/css/data-type/color.md)

## Formal definition


<PropertyDefinition initialValue={<>0px</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
transparent | <color>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-start-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-color)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-start-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-start-style.md
---

<APISummary />

## Introduction

The `border-inline-start-style` CSS property defines the style of the logical inline start border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-left-style`](/api/css/properties/border-left-style.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-style`](/api/css/properties/border-right-style.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-inline-start-style`
**Bundle:** `dist/border-inline-start-style.lynx.bundle`

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

const BorderInlineStartStyle = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartStyle: "dashed",
    borderInlineEndStyle: "solid",
  } as const;

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineStartStyle />);

```



## Syntax

```css
border-inline-start-style: none;
border-inline-start-style: hidden;
border-inline-start-style: dotted;
border-inline-start-style: dashed;
border-inline-start-style: solid;
border-inline-start-style: double;
border-inline-start-style: groove;
border-inline-start-style: ridge;
border-inline-start-style: inset;
border-inline-start-style: outset;
```

### Values

- `none`

- `hidden`

- `dotted`

- `dashed`

- **default** `solid`

- `double`

- `groove`

- `ridge`

- `inset`

- `outset`

## Formal definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-start-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-style)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-start-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-start-width.md
---

<APISummary />

## Introduction

The `border-inline-start-width` CSS property defines the width of the logical inline-start border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-left-width`](/api/css/properties/border-left-width.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-width`](/api/css/properties/border-right-width.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-inline-start-width`
**Bundle:** `dist/border-inline-start-width.lynx.bundle`

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

const BorderInlineStartWidth = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartWidth: "5px",
    borderInlineEndWidth: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineStartWidth />);

```



## Syntax

```css
border-inline-start-width: thin;
border-inline-start-width: medium;
border-inline-start-width: thick;
border-inline-start-width: 10px;
```

### Values

- `thin`

- `medium`

- `thick`

- [`<length>`](/api/css/data-type/length.md)

## Formal definition


<PropertyDefinition initialValue={<>0px</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
thin | medium | thick | <length>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-start-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-width)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-start-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left-color.md
---

<APISummary />

## Introduction

Used to set the color of the left border.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-left-color`
**Bundle:** `dist/border-left-color.lynx.bundle`

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

const BorderLeftColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderLeftColor />);

```



## Syntax

```css
border-left-color: red;
border-left-color: #ffbb00;
border-left-color: rgb(255, 0, 0);
border-left-color: hsla(100%, 50%, 25%, 0.75);
border-left-color: currentColor;
border-left-color: transparent;
```

### Values

- `transparent`
  The border color is transparent.

- [`<color>`](/api/css/data-type/color.md)
  The specific color of the border.

## Formal definition


<PropertyDefinition initialValue={<>transparent</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

```
transparent | <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left-style.md
---

<APISummary />

## Introduction

The **border-left-style** CSS property sets the line style of an element's left [`border`](/api/css/properties/border.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-left-style`
**Bundle:** `dist/border-left-style.lynx.bundle`

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

const BorderLeftStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderLeftStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderLeftStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderLeftStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderLeftStyle />);

```



## Syntax

```css
border-left-style: none;
border-left-style: hidden;
border-left-style: dotted;
border-left-style: dashed;
border-left-style: solid;
border-left-style: double;
border-left-style: groove;
border-left-style: ridge;
border-left-style: inset;
border-left-style: outset;
```

### Values

- `none`
  Like the `hidden` keyword, displays no border.

- `hidden`
  Like the `none` keywork, displays no border.

- `dotted`
  Displays a series of rounded dots. The spacing of the dots is not defined by the specification and is implementation-specific. The radius of the dots is half the computed value of the same side's [`border-width`](/api/css/properties/border-width.md).

- `dashed`
  Displays a series of short square-ended dashes or line segments. The exact size and length of the segments are not defined by the specification and are implementation-specific.

- `solid`
  Displays a single, straight, solid line.

- `double`
  Displays two straight lines that add up to the pixel size defined by [`border-width`](/api/css/properties/border-width.md).

- `groove`
  Displays a border with a carved appearance. It is the opposite of ridge.

- `ridge`
  Displays a border with an extruded appearance. It is the opposite of groove.

- `inset`
  Displays a border that makes the element appear embedded. It is the opposite of outset.

- `outset`
  Displays a border that makes the element appear embossed. It is the opposite of inset.

## Formal definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
<line-style>
where
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Differences from web

- [mdn:border-left-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-style)

Global values are not supported (inherit, initial, revert, unset, etc).

When value is 'none' or 'hidden', the `border-width` value is not 0.

Default value is 'solid'.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left-width.md
---

# border-left-width

<APISummary />

## Introduction

Used to set the width of the left border.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-left-width`
**Bundle:** `dist/border-left-width.lynx.bundle`

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

const BorderLeftWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderLeftWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderLeftWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderLeftWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderLeftWidth />);

```



## Syntax

```css
border-left-width: thin;
border-left-width: medium;
```

### Values

- `thin`
  Thin border.

- `medium`
  Medium border.

- `thick`
  Thick border.

- [`<length>`](/api/css/data-type/length.md)
  Defines the border width with a specific size.

## Formal Definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>All elements</>} inherited="no" animatable="yes" />

## Formal Syntax

```css
border-left-width = <line-width>
<line-width> = thin | medium | thick | <length>
```

## Differences from the Web

- [mdn:border-left-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width)
- Does not support `inherit`, `initial`, `revert`, or `unset`.
- Default value is `0`, whereas the web default is `medium`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left.md
---

# border-left

<APISummary />

## Introduction

A shorthand property for setting the left border styles of an element. It includes [`border-left-width`](/api/css/properties/border-left-width.md), [`border-left-style`](/api/css/properties/border-left-style.md), and [`border-left-color`](/api/css/properties/border-left-color.md) in order.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-left`
**Bundle:** `dist/border-left.lynx.bundle`

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

const BorderLeft = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`normal-${rowIndex}-${colIndex}`}
                  className="box"
                  style={{ borderLeft: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderLeft: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderLeft />);

```



## Syntax

```css
border-left: 1px solid red;
```

## Values

Can be set in order as follows:

- [`border-left-width`](/api/css/properties/border-left-width.md)
  The width of the border.

- [`border-left-style`](/api/css/properties/border-left-style.md)
  The style of the border.

- [`border-left-color`](/api/css/properties/border-left-color.md)
  The color of the border.

## Formal Definition


<PropertyDefinition initialValue={<>Empty</>} appliesTo={<>All elements</>} inherited="no" animatable="no" />

## Formal Syntax

```css
border-left = <line-width> <line-style> <color>
```

## Differences from the Web

- [mdn:border-left](https://developer.mozilla.org/en-US/docs/Web/CSS/border-left)
- Does not support `inherit`, `initial`, `revert`, or `unset`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-radius.md
---

<APISummary />

## Introduction

The border-radius CSS property rounds the corners of an element's outer border edge. You can set a single radius to make circular corners, or two radii to make elliptical corners.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-radius`
**Bundle:** `dist/border-radius.lynx.bundle`

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

const BorderRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em / 5em"],
    ["2em 1em 4em / 0.5em 3em", "15px 50px"],
    ["15px 50px 30px 5px", "1em 2em 4em 4em / 1em 2em 2em 8em"],
    ["100px 200px", "100px 30px / 10px"],
    ["100em / 200em", "2px 0px 2em / 0em 100px"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRadius />);

```



## Syntax

```css
/* The syntax of the first radius allows one to four values */
/* Radius is set for all 4 sides */
border-radius: 10px;

/* top-left-and-bottom-right | top-right-and-bottom-left */
border-radius: 10px 5%;

/* top-left | top-right-and-bottom-left | bottom-right */
border-radius: 2px 4px 2px;

/* top-left | top-right | bottom-right | bottom-left */
border-radius: 1px 0 3px 4px;

/* The syntax of the second radius allows one to four values */
/* (first radius values) / radius */
border-radius: 10px / 20px;

/* (first radius values) / top-left-and-bottom-right | top-right-and-bottom-left */
border-radius: 10px 5% / 20px 30px;

/* (first radius values) / top-left | top-right-and-bottom-left | bottom-right */
border-radius: 10px 5px 2em / 20px 25px 30%;

/* (first radius values) / top-left | top-right | bottom-right | bottom-left */
border-radius: 10px 5% / 20px 25em 30px 35em;
```

The `border-radius` property is specified as:

- one, two, three, or four [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) values. This is used to set a single radius for the corners.
- followed optionally by "/" and one, two, three, or four [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md)values. This is used to set an additional radius, so you can have elliptical corners.

### Values

- [`<length>`](/api/css/data-type/length.md)
  Denotes the size of the circle radius, or the semi-major and semi-minor axes of the ellipse, using length values. Negative values are invalid.

- [`<percentage>`](/api/css/data-type/percentage.md)
  Denotes the size of the circle radius, or the semi-major and semi-minor axes of the ellipse, using percentage values. Percentages for the horizontal axis refer to the width of the box; percentages for the vertical axis refer to the height of the box. Negative values are invalid.

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
border-radius =
  <length-percentage [0,∞]>{1,4} [ / <length-percentage [0,∞]>{1,4} ]?

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference from Web

- [mdn:border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius)

Global values are not supported, (inherit, initial, revert, unset, etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right-color.md
---

<APISummary />

## Introduction

Used to set the color of the right border.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-right-color`
**Bundle:** `dist/border-right-color.lynx.bundle`

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

const BorderRightColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderRightColor />);

```



## Syntax

```css
border-right-color: red;
border-right-color: #ffbb00;
border-right-color: rgb(255, 0, 0);
border-right-color: hsla(100%, 50%, 25%, 0.75);
border-right-color: currentColor;
border-right-color: transparent;
```

### Values

- `transparent`
  The border color is transparent.

- [`<color>`](/api/css/data-type/color.md)
  The specific color of the border.

## Formal definition


<PropertyDefinition initialValue={<>transparent</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

```
transparent | <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right-style.md
---

<APISummary />

## Introduction

The **border-right-style** CSS property sets the line style of an element's right [`border`](/api/css/properties/border.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-right-style`
**Bundle:** `dist/border-right-style.lynx.bundle`

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

const BorderRightStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderRightStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderRightStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderRightStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRightStyle />);

```



## Syntax

```css
border-right-style: none;
border-right-style: hidden;
border-right-style: dotted;
border-right-style: dashed;
border-right-style: solid;
border-right-style: double;
border-right-style: groove;
border-right-style: ridge;
border-right-style: inset;
border-right-style: outset;
```

### Values

- `none`
  Like the `hidden` keyword, displays no border.

- `hidden`
  Like the `none` keywork, displays no border.

- `dotted`
  Displays a series of rounded dots. The spacing of the dots is not defined by the specification and is implementation-specific. The radius of the dots is half the computed value of the same side's [`border-width`](/api/css/properties/border-width.md).

- `dashed`
  Displays a series of short square-ended dashes or line segments. The exact size and length of the segments are not defined by the specification and are implementation-specific.

- `solid`
  Displays a single, straight, solid line.

- `double`
  Displays two straight lines that add up to the pixel size defined by [`border-width`](/api/css/properties/border-width.md).

- `groove`
  Displays a border with a carved appearance. It is the opposite of ridge.

- `ridge`
  Displays a border with an extruded appearance. It is the opposite of groove.

- `inset`
  Displays a border that makes the element appear embedded. It is the opposite of outset.

- `outset`
  Displays a border that makes the element appear embossed. It is the opposite of inset.

## Formal definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
<line-style>
where
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Differences from web

- [mdn:border-right-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-style)

Global values are not supported (inherit, initial, revert, unset, etc).

When value is 'none' or 'hidden', the `border-width` value is not 0.

Default value is 'solid'.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right-width.md
---

<APISummary />

## Introduction

The border-right-width CSS property sets the width of the left border of an element.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-right-width`
**Bundle:** `dist/border-right-width.lynx.bundle`

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

const BorderRightWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderRightWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderRightWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderRightWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRightWidth />);

```



## Syntax

```css
/* Keyword values */
border-right-width: thin;
border-right-width: medium;
border-right-width: thick;

/* <length> values */
border-right-width: 10rem;
border-right-width: 6px;
```

### Values

`<line-width>`

Defines the width of the border, either as an explicit nonnegative [`<length>`](/api/css/data-type/length.md) or a keyword. If it's a keyword, it must be one of the following values:

- thin
- medium
- thick

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

```
border-right-width =
  <line-width>

<line-width> =
  <length [0,∞]>  |
  thin            |
  medium          |
  thick
```

## Difference from Web

- [mdn:border-right-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width)

Global values are not supported (inherit, initial, revert, unset, etc).

Default value is 0, different to 'medium' in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right.md
---

<APISummary />

## Introduction

The border-right shorthand CSS property sets all the properties of an element's right border.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-right`
**Bundle:** `dist/border-right.lynx.bundle`

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

const BorderRight = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`normal-${rowIndex}-${colIndex}`}
                  className="box"
                  style={{ borderRight: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderRight: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRight />);

```



## Syntax

```css
.br-0 {
  border-right: thick double red;
}
.br-1 {
  border-right: thin dotted blue;
}

.br-2 {
  border-right: 10px dashed orange;
}
```

### Values

This property is a shorthand for the following CSS properties:

- [`border-right-width`](/api/css/properties/border-right-width.md)
  width of the border

- [`border-right-style`](/api/css/properties/border-right-style.md)
  style of the border

- [`border-right-color`](/api/css/properties/border-right-color.md)
  color of the border

## Formal definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
<line-width> || <line-style> || <color>
where
<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Difference from Web

- [mdn:border-right](https://developer.mozilla.org/en-US/docs/Web/CSS/border-right)

Global values are not supported. (inherit, initial, revert, unset, etc)

Default style value is `solid`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-start-end-radius.md
---

<APISummary />

## Introduction

The `border-start-end-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-top-right-radius`](/api/css/properties/border-top-right-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-top-left-radius`](/api/css/properties/border-top-left-radius.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-start-end-radius`
**Bundle:** `dist/border-start-end-radius.lynx.bundle`

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

const BorderStartEndRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderStartEndRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderStartEndRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-end-radius: radius */
border-start-end-radius: 3px;

/* the corner is an ellipsis */
/* border-end-end-radius: horizontal vertical */
border-start-end-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]?
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-start-end-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-start-end-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-start-end-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-end-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-end-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-start-start-radius.md
---

<APISummary />

## Introduction

The `border-start-start-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-top-left-radius`](/api/css/properties/border-top-left-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-top-right-radius`](/api/css/properties/border-top-right-radius.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-start-start-radius`
**Bundle:** `dist/border-start-start-radius.lynx.bundle`

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

const BorderStartStartRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderStartStartRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderStartStartRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-start-radius: radius */
border-end-start-radius: 3px;

/* the corner is an ellipsis */
/* border-end-start-radius: horizontal vertical */
border-end-start-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
[<length> | <percentage>] [[<length> | <percentage>]]?
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-start-start-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-start-start-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-start-start-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-start-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-start-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-style.md
---

# border-style

<APISummary />

## Introduction

Used to set the styles of all four borders. This property can define the styles for the top, right, bottom, and left borders in order.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-style`
**Bundle:** `dist/border-style.lynx.bundle`

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

const BorderStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
    ["dotted groove", "dotted solid double", "groove solid double dashed"],
    ["outset inset", "solid none dashed", "dotted solid dashed inset"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidthSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidthSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-same-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-same-${rowIndex}-${colIndex}`}
                  className="box colorWidthDiff2 radiusSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-diff-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-diff-${rowIndex}-${colIndex}`}
                  className="box colorWidthDiff radiusDiff"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderStyle />);

```



## Syntax

```css
border-style: double solid dotted dashed;
```

### Values

- none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
- Supports 1-4 value syntax (top → right → bottom → left).

## Formal Definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>All elements</>} inherited="no" animatable="no" />

## Formal Syntax

```css
border-style = [ <line-style> ]{1,4}
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style)
- Default value is different (Web default is `none`).
- When the value is `none` or `hidden`, the border width remains unchanged (Web sets it to `0`).
- Does not support `inherit`, `initial`, `revert`, or `unset` global values.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-color.md
---

<APISummary />

## Introduction

Used to set the color of the top border.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-top-color`
**Bundle:** `dist/border-top-color.lynx.bundle`

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

const BorderTopColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderTopColor />);

```



## Syntax

```css
border-top-color: red;
border-top-color: #ffbb00;
border-top-color: rgb(255, 0, 0);
border-top-color: hsla(100%, 50%, 25%, 0.75);
border-top-color: currentColor;
border-top-color: transparent;
```

### Values

- `transparent`
  The border color is transparent.

- [`<color>`](/api/css/data-type/color.md)
  The specific color of the border.

## Formal definition


<PropertyDefinition initialValue={<>transparent</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

```
transparent | <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-left-radius.md
---

<APISummary />

## Introduction

The border-top-left-radius CSS property rounds the bottom-left corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-top-left-radius`
**Bundle:** `dist/border-top-left-radius.lynx.bundle`

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

const BorderTopLeftRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopLeftRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-top-left-radius: radius */
border-top-left-radius: 3px;

/* Percentage values */

/* circle if box is a square or ellipse if box is a rectangle */
border-top-left-radius: 20%;

/* same as above: 20% of horizontal(width) and vertical(height) */
border-top-left-radius: 20% 20%;

/* 20% of horizontal(width) and 10% of vertical(height) */
border-top-left-radius: 20% 10%;

/* the corner is an ellipse */
/* border-top-left-radius: horizontal vertical */
border-top-left-radius: 0.5em 1em;
```

With one value:

- the value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the radius of the circle to use for the border in that corner.

With two values:

- the first value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the horizontal semi-major axis of the ellipse to use for the border in that corner.
- the second value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the vertical semi-major axis of the ellipse to use for the border in that corner.

### Values

`<length-percentage>`

Denotes the size of the circle radius or the semi-major and semi-minor axes of the ellipse. As absolute length it can be expressed in any unit allowed
by the CSS [`<length>`](/api/css/data-type/length.md) data type. Percentages for the horizontal axis refer to the width of the box, percentages for the vertical
axis refer to the height of the box. Negative values are invalid.

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
border-top-left-radius =
  <length-percentage [0,∞]>{1,2}

<length-percentage> =
  <length>      |
  <percentage>
```

Examples:

```css
/* the corner is a circle */
/* border-top-left-radius: radius */
border-top-left-radius: 3px;

/* the corner is an ellipsis */
/* border-top-left-radius: horizontal vertical */
border-top-left-radius: 0.5em 1em;
```

## Difference from Web

- [mdn:border-top-left-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-left-radius)

Global values are not supported, (inherit, initial, revert, unset, etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-left-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-left-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-left-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-right-radius.md
---

<APISummary />

## Introduction

The border-top-right-radius CSS property rounds the bottom-left corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-top-right-radius`
**Bundle:** `dist/border-top-right-radius.lynx.bundle`

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

const BorderTopRightRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopRightRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-top-right-radius: radius */
border-top-right-radius: 3px;

/* Percentage values */

/* circle if box is a square or ellipse if box is a rectangle */
border-top-right-radius: 20%;

/* same as above: 20% of horizontal(width) and vertical(height) */
border-top-right-radius: 20% 20%;

/* 20% of horizontal(width) and 10% of vertical(height) */
border-top-right-radius: 20% 10%;

/* the corner is an ellipse */
/* border-top-right-radius: horizontal vertical */
border-top-right-radius: 0.5em 1em;
```

With one value:

- the value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the radius of the circle to use for the border in that corner.

With two values:

- the first value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the horizontal semi-major axis of the ellipse to use for the border in that corner.
- the second value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the vertical semi-major axis of the ellipse to use for the border in that corner.

### Values

`<length-percentage>`

Denotes the size of the circle radius or the semi-major and semi-minor axes of the ellipse. As absolute length it can be expressed in any unit allowed
by the CSS [`<length>`](/api/css/data-type/length.md) data type. Percentages for the horizontal axis refer to the width of the box, percentages for the vertical
axis refer to the height of the box. Negative values are invalid.

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
border-top-right-radius =
  <length-percentage [0,∞]>{1,2}

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference from Web

- [mdn:border-top-right-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-right-radius)

Global values are not supported, (inherit, initial, revert, unset, etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-right-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-right-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-right-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-style.md
---

<APISummary />

## Introduction

The `border-top-style` CSS property sets the line style of an element's top [`border`](/api/css/properties/border.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-top-style`
**Bundle:** `dist/border-top-style.lynx.bundle`

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

const BorderTopStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-same-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-same-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-diff-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-diff-${rowIndex}-${colIndex}`}
                  className="box colorWidth1 radiusDiff"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopStyle />);

```



## Syntax

```css
border-top-style: none;
border-top-style: hidden;
border-top-style: dotted;
border-top-style: dashed;
border-top-style: solid;
border-top-style: double;
border-top-style: groove;
border-top-style: ridge;
border-top-style: inset;
border-top-style: outset;
```

### Values

- `none`
  Like the `hidden` keyword, displays no border.

- `hidden`
  Like the `none` keywork, displays no border.

- `dotted`
  Displays a series of rounded dots. The spacing of the dots is not defined by the specification and is implementation-specific. The radius of the dots is half the computed value of the same side's [`border-width`](/api/css/properties/border-width.md).

- `dashed`
  Displays a series of short square-ended dashes or line segments. The exact size and length of the segments are not defined by the specification and are implementation-specific.

- `solid`
  Displays a single, straight, solid line.

- `double`
  Displays two straight lines that add up to the pixel size defined by [`border-width`](/api/css/properties/border-width.md).

- `groove`
  Displays a border with a carved appearance. It is the opposite of ridge.

- `ridge`
  Displays a border with an extruded appearance. It is the opposite of groove.

- `inset`
  Displays a border that makes the element appear embedded. It is the opposite of outset.

- `outset`
  Displays a border that makes the element appear embossed. It is the opposite of inset.

## Formal definition


<PropertyDefinition initialValue={<>solid</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
<line-style>
where
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Differences from web

- [mdn:border-top-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-style)

Global values are not supported (inherit, initial, revert, unset, etc).

When value is 'none' or 'hidden', the `border-width` value is not 0.

Default value is 'solid'.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-width.md
---

<APISummary />

## Introduction

The border-top-width CSS property sets the width of the left border of an element.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-top-width`
**Bundle:** `dist/border-top-width.lynx.bundle`

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

const BorderTopWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderTopWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderTopWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderTopWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopWidth />);

```



## Syntax

```css
/* Keyword values */
border-top-width: thin;
border-top-width: medium;
border-top-width: thick;

/* <length> values */
border-top-width: 10rem;
border-top-width: 6px;
```

### Values

`<line-width>`

Defines the width of the border, either as an explicit nonnegative [`<length>`](/api/css/data-type/length.md) or a keyword. If it's a keyword, it must be one of the following values:

- thin
- medium
- thick

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

```
border-top-width =
  <line-width>

<line-width> =
  <length [0,∞]>  |
  thin            |
  medium          |
  thick
```

## Difference from Web

- [mdn:border-top-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width)

Global values are not supported (inherit, initial, revert, unset, etc).

Default value is 0, different to 'medium' in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top.md
---

<APISummary />

## Introduction

The border-top shorthand CSS property sets all the properties of an element's right border.

## Examples

**This is an example below:  css-api**

**Entry:** `src/border-top`
**Bundle:** `dist/border-top.lynx.bundle`

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

const BorderTop = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`normal-${rowIndex}-${colIndex}`}
                  className="box"
                  style={{ borderTop: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderTop: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTop />);

```



## Syntax

```css
.border {
  border-top: 1px;
}
```

It is actually the same as this one:

```css
.border {
  border-top: 1px solid black;
}
```

### Values

This property is a shorthand for the following CSS properties:

- [`border-top-width`](/api/css/properties/border-top-width.md)
  width of the border

- [`border-top-style`](/api/css/properties/border-top-style.md)
  style of the border

- [`border-top-color`](/api/css/properties/border-top-color.md)
  color of the border

As with all shorthand properties, border-top always sets the values of all the properties that it can set,
even if they are not specified. It sets those that are not specified to their default values. Consider the following code:

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
<line-width> || <line-style> || <color>
where
<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Difference from Web

- [mdn:border-top](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top)

Global values are not supported. (inherit, initial, revert, unset, etc)

Default style value is `solid`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-width.md
---

# border-width

<APISummary />

## Introduction

A shorthand property for setting the width of all four borders of an element. It corresponds to [`border-top-width`](/api/css/properties/border-top-width.md), [`border-right-width`](/api/css/properties/border-right-width.md), [`border-bottom-width`](/api/css/properties/border-bottom-width.md), and [`border-left-width`](/api/css/properties/border-left-width.md).

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/border-width`
**Bundle:** `dist/border-width.lynx.bundle`

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

const BorderWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "thin medium"],
    ["thin medium thick", "thin medium thick 10px"],
    ["5px 1px 0px 15px", "0.5px 0.2em 5rpx"],
    ["0.2em 0.4em 0.5rem 3rpx", "thick 1px"],
  ];

  const widthOptions2 = [
    ["thick", "thick thin"],
    ["medium thick 1px", "thick 10px"],
    ["5px 0px 15px", "0.5px 5rpx 1rem"],
    ["0.2em 0.5rem 3rpx", "thick 6px"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions2.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderWidth />);

```



## Syntax

```css
border-width: thin medium thick 10px;
```

### Values

- thin | medium | thick | [`<length>`](/api/css/data-type/length.md)
- Supports 1-4 value syntax (top → right → bottom → left).

## Formal Definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>All elements</>} inherited="no" animatable="yes" />

## Formal Syntax

```css
border-width = [ <line-width> ]{1,4}
<line-width> = <length> | thin | medium | thick
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width)
- Default value is different (Web default is `medium`).
- Does not support global values.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border.md
---

<APISummary />

## Introduction

The border shorthand CSS property sets an element's border. It sets the values of [border-width](/api/css/properties/border-width.md), [border-style](/api/css/properties/border-style.md), and [border-color](/api/css/properties/border-color.md).

## Examples

**This is an example below:  css-api**

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

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

const Border = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px solid orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      s
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view key={`normal-${rowIndex}-${colIndex}`} className="box" style={{ border: borderStyle }}>
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ border: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<Border />);

```



## Syntax

```css
/* style */
border: solid;

/* width | style */
border: 2px dotted;

/* style | color */
border: outset #f33;

/* width | style | color */
border: medium dashed green;
```

### Values

This property is a shorthand for the following CSS properties:

- [`border-width`](/api/css/properties/border-width.md)
  Sets the thickness of the border.

- [`border-style`](/api/css/properties/border-style.md)
  Sets the style of the border.

- [`border-color`](/api/css/properties/border-color.md)
  Sets the color of the border.

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

{' '}

## Formal syntax

```
<line-width> || <line-style> || <color>
where
<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Difference between web

- [mdn:border](https://developer.mozilla.org/en-US/docs/Web/CSS/border)

Lynx does not support inherit, initial, revert, or unset.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/bottom.md
---

<APISummary />

## Introduction

The `bottom` CSS property participates in specifying the vertical position. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `bottom` depends on how the element is positioned (i.e., the value of the position property):

- When position is set to `absolute` or `fixed`, the `bottom` property specifies the distance between the outer edge of the element's bottom margin and the outer edge of the containing block's bottom padding.

- When `position` is set to `relative`, the `bottom` property specifies the distance the element's bottom edge is moved above its normal position.

When both `top` and `bottom` are specified, position is set to `absolute` or `fixed`, and `height` is unspecified (either `auto` or 100%) both the `top` and `bottom` distances are respected. In all other situations, if `height` is constrained in any way or `position` is set to `relative`, the top property takes precedence and the `bottom` property is ignored.

## Examples

**This is an example below:  css-api**

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

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

const Bottom = () => {
  const containerStyle = {
    width: "210px",
    height: "210px",
    border: "5px",
    borderColor: "black",
  };

  const firstBoxStyle = {
    position: "absolute" as const,
    bottom: "80px",
    width: "50px",
    height: "50px",
    backgroundColor: "red",
  };

  const secondBoxStyle = {
    position: "fixed" as const,
    bottom: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "green",
  };

  const thirdBoxStyle = {
    position: "relative" as const,
    bottom: "10px",
    width: "50px",
    height: "50px",
    backgroundColor: "yellow",
  };

  const fourthBoxStyle = {
    width: "50px",
    height: "50px",
    backgroundColor: "blue",
  };

  return (
    <view style={containerStyle}>
      <view style={firstBoxStyle}></view>
      <view style={secondBoxStyle}></view>
      <view style={thirdBoxStyle}></view>
      <view style={fourthBoxStyle}></view>
    </view>
  );
};

root.render(<Bottom />);

```



## Syntax

```css
/* <length> values */
bottom: 3px;
bottom: 2rpx;
bottom: 2.4em;
bottom: 3rem;

bottom: 10%;

/* Keyword value */
bottom: auto;

/* calc */
bottom: calc(1px + 1px);
```

### Values

- [`<length>`](/api/css/data-type/length.md)

  A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

  - for absolutely positioned elements, the distance to the bottom edge of the containing block.
  - for relatively positioned elements, the distance that the element is moved above its normal position.

- [`<percentage>`](/api/css/data-type/percentage.md)

  Defines the height as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s height.

- `auto`

  **Default value**.

## Formal definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" percentages={<>refer to the height of the containing block</>} />

## Formal syntax

```
bottom =
  auto                |
  <length-percentage>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/box-shadow.md
---

<APISummary />

## Introduction

The `box-shadow` CSS property is used to add a shadow effect on the frame of the element. The values that can be set by this property include X-axis offset, Y-axis offset, shadow blur radius, shadow diffusion radius and shadow color, which are separated by multiple commas. `box-shadow` describes one or more shadow effects in a comma-separated list. This property allows the borders of almost all elements to be shaded. If the element is set `border-radius` at the same time, shadows will also have rounded corners. Order of multiple shadows in z-axis is the same rule as multiple `text shadows` (the first shadow is at the top).

## Syntax

```css
/* Keyword values */
box-shadow: none;

/* offset-x | offset-y | color */
box-shadow: 60px -16px teal;

/* offset-x | offset-y | blur-radius | color */
box-shadow: 10px 5px 5px black;

/* offset-x | offset-y | blur-radius | spread-radius | color */
box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);

/* inset | offset-x | offset-y | color */
box-shadow: inset 5em 1em gold;

/* Any number of shadows, separated by commas */
box-shadow:
  3px 3px red,
  -1em 0 0.4em olive;
```

### Values

- A case where two, three, or four numeric values are given.

  - If only two values are given, these two values will be interpreted by the browser as an offset on the x-axis`<offset-x>`And`y`Offset on axis`<offset-y>`。
  - If a third value is given, this third value will be interpreted as the size of the blur radius`<blur-radius>`。
  - If the fourth value is given, this fourth value will be interpreted as the size of the extended radius`<spread-radius>`。

- Optional, insert (shadow inward)`inset`。

- Optional, color value`<color>`。

## Formal Definition


<PropertyDefinition initialValue={<code>none</code>} appliesTo={<>All elements</>} inherited="no" animatable="no" />

## Formal Syntax

```
box-shadow =
  <box-shadow-position> &&
  [ <'box-shadow-offset'> [ <'box-shadow-blur'> <'box-shadow-spread'>? ]? ] &&
  <box-shadow-color>

<box-shadow-postion> =
  inset?

<box-shadow-offset> =
  <length>{2}

<box-shadow-blur> =
  <length [0, ∞]>

```

## Difference from Web

- [mdn: box-sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow)

Temporarily not support values like inherit、initial、revert、unset、inset.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.box-shadow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-shadow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-shadow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/box-sizing.md
---

<APISummary />

## Introduction

The `box-sizing` property defines whether fixed sizes (such as `<length>`s and `<percentage>`s) are assigned to the content box or to the border box. It affects the interpretation of all sizing properties, including [`width`](/api/css/properties/width.md), [`height`](/api/css/properties/height.md), [`min-width`](/api/css/properties/min-width.md), [`min-height`](/api/css/properties/min-height.md), [`max-width`](/api/css/properties/max-width.md), [`max-height`](/api/css/properties/max-height.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/box-sizing`
**Bundle:** `dist/box-sizing.lynx.bundle`

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

const BoxSizing = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
    background: "white",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="div1">
          <text>FL</text>
        </view>
        <view className="div2">
          <text>FR</text>
        </view>

        <view className="div3">
          <text>BL</text>
        </view>
        <view className="div4">
          <text>BR</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<BoxSizing />);

```



## Syntax

```css
box-sizing: border-box;
box-sizing: content-box;
```

### Values

- `border-box`

  **Default value**. The [`width`](/api/css/properties/width.md) and [`height`](/api/css/properties/height.md) properties include the content, padding, and border, but do not include the margin.

  Size calculation formula:

  width = border + padding + content

  height = border + padding + content

- `content-box`

  The [`width`](/api/css/properties/width.md) and [`height`](/api/css/properties/height.md) properties include the content, but does not include the padding, border, or margin.

  Size calculation formula:

  width = content

  height = content

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>border-box</code>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  animatable="no"
/>

## Formal syntax

```
box-sizing = border-box | content-box
```

## Difference with the web

- Default value is `border-box` in Lynx, while `content-box` in web.
- It will not affect the interpretation of [`flex-basis`](/api/css/properties/flex-basis.md), while Web will.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.box-sizing`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-sizing](https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-sizing)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/clip-path.md
---

# clip-path

<APISummary />

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&icon_names=android" />

## Introduction

The `clip-path` CSS property creates a clipping region that sets what part of an element should be shown. Parts that are inside the region are shown, while those outside are hidden.

:::warning

- `clip-path` takes effect only on `<view>` elements.

- <span className="material-symbols-outlined">android</span> If this property is
  not work on Android，try to add a transparent background `background-color:
  transparent` to avoid the clipping process from being skipped by system.

:::

## Examples

### **inset**

{' '}

**This is an example below:  css-api**

**Entry:** `src/clip_path/inset`
**Bundle:** `dist/clip_path_inset.lynx.bundle`

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

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        clipPath: "inset(30px super-ellipse 3 3 50px/50px)",
      }}
    >
    </view>
  );
}

root.render(<App />);

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

```



### **circle**

{' '}

**This is an example below:  css-api**

**Entry:** `src/clip_path/circle`
**Bundle:** `dist/clip_path_circle.lynx.bundle`

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

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        clipPath: "circle(50% at 50% top)",
      }}
    >
    </view>
  );
}

root.render(<App />);

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

```



### **ellipse**

{' '}

**This is an example below:  css-api**

**Entry:** `src/clip_path/ellipse`
**Bundle:** `dist/clip_path_ellipse.lynx.bundle`

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

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        background: "linear-gradient(to bottom right, rgb(255,53,26), rgb(0,235,235) 50%)",
        clipPath: "ellipse(50px 60px at 10% 20%)",
      }}
    >
    </view>
  );
}

root.render(<App />);

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

```



### **path**

{' '}

**This is an example below:  css-api**

**Entry:** `src/clip_path/path`
**Bundle:** `dist/clip_path_path.lynx.bundle`

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

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        background: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235) 50%)",
        clipPath:
          "path('M36.9273 55.6337C35.2784 54.9693 33.3921 55.354 32.1351 56.611L31.9808 56.7653C30.3346 58.4116 27.6654 58.4116 26.0191 56.7653C24.803 55.5492 22.9701 55.1938 21.3876 55.8672C19.2453 56.7789 16.7696 55.7813 15.8579 53.639L15.7725 53.4383C15.0764 51.8026 13.4706 50.7408 11.6929 50.7408H11.4748C9.14659 50.7408 7.25919 48.8534 7.25919 46.5252C7.25919 44.8053 6.21441 43.2579 4.61919 42.6151C2.45972 41.745 1.41453 39.289 2.28469 37.1295L2.3662 36.9272C3.0306 35.2784 2.64593 33.3921 1.38892 32.1351L1.23471 31.9809C-0.411583 30.3346 -0.411564 27.6654 1.23473 26.0191C2.45085 24.803 2.80627 22.97 2.1328 21.3875C1.22113 19.2453 2.21872 16.7695 4.36099 15.8579L4.56168 15.7725C6.1974 15.0764 7.25919 13.4705 7.25919 11.6929V11.4747C7.25919 9.14657 9.14655 7.25922 11.4747 7.25922C13.1946 7.25922 14.742 6.21442 15.3848 4.61921C16.2549 2.45972 18.711 1.41448 20.8705 2.28466L21.0728 2.36618C22.7217 3.03059 24.6079 2.64592 25.8649 1.38891L26.0191 1.23471C27.6654 -0.411569 30.3346 -0.41157 31.9808 1.23471C33.197 2.45083 35.0299 2.80623 36.6124 2.13277C38.7547 1.22109 41.2305 2.21868 42.1422 4.36097L42.2276 4.5617C42.9237 6.19742 44.5295 7.25921 46.3072 7.25921H46.5253C48.8535 7.25921 50.7408 9.14656 50.7408 11.4747C50.7408 13.1946 51.7856 14.742 53.3808 15.3847C55.5402 16.2549 56.5854 18.7109 55.7153 20.8704L55.6337 21.0727C54.9693 22.7216 55.354 24.6079 56.611 25.8649L56.7653 26.0192C58.4116 27.6654 58.4116 30.3346 56.7653 31.9808C55.5492 33.1969 55.1938 35.0299 55.8672 36.6124C56.7789 38.7547 55.7813 41.2304 53.6391 42.1421L53.4384 42.2275C51.8026 42.9236 50.7408 44.5294 50.7408 46.3071V46.5252C50.7408 48.8534 48.8534 50.7408 46.5252 50.7408C44.8053 50.7408 43.2579 51.7856 42.6151 53.3808C41.745 55.5402 39.289 56.5854 37.1296 55.7153L36.9273 55.6337Z')",
      }}
    >
    </view>
  );
}

root.render(<App />);

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

```



## Syntax

```css
/* Keyword values */
clip-path: none;

/* <basic-shape> values */
clip-path: inset(30px super-ellipse 3 3 50px/50px);
clip-path: circle(50px at 0 100px);
clip-path: ellipse(50px 60px at 10% 20%);
clip-path: path(
  'M0.5,1 C0.5,1,0,0.7,0,0.3 A0.25,0.25,1,1,1,0.5,0.3 A0.25,0.25,1,1,1,1,0.3 C1,0.7,0.5,1,0.5,1 Z'
);
```

### Values

The `clip-path` property is specified as one of the values listed below.

`none`

No clipping path is created.

`<basic-shape>`

A shape whose size and position is defined by its `border-box`. One of:

- `inset()`

Defines an inset rectangle.

```
inset( <length-percentage>{1, 4} [ round | (super-ellipse <exponents>) <border-radius>]?)

<length-percentage> =
  <length>
  <percentage>

<exponents> = <number>{2}

<border-radius> =
  <length-percentage [0,∞]>{1,4} [ / <length-percentage [0,∞]>{1,4} ]?
```

`<length-percentage>{1, 4}`

They represent the top, right, bottom, and left offsets from the `border-box` that defines the positions of the edges of the inset rectangle. These arguments follow the syntax of the margin shorthand, which let
you set all four insets with one, two or four values.

`round | (super-ellipse <exponents>) <border-radius>`

Optional arguments to define the rounded corners for the inset rectangle. When the shape is `round`, the corner radius acts like `<border-radius>`. When the shapes is `super-ellipse <exponent>`, the corner curve will be an [lame curve](https://en.wikipedia.org/wiki/Superellipse) 。`<border-radius>` using the border-radius shorthand syntax.

`<exponent>`

The two number are the exponents on the two dimensions, first is for x-axis and next for y-axis.

- `circle()`

Defines a circle using a radius and a position.

```
circle(<length-percentage> [at <position>]?)

<length-percentage> =
  <length [0,∞]>                |
  <percentage [0,∞]>

<position> =
  [ left | center | right | top | bottom | <length-percentage> ]  |
  [ left | center | right ] && [ top | center | bottom ]  |
  [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]  |
  [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ]
```

`<length-percentage>`

This may be a `<length>`, or a `<percentage>` defining the radius of the circle.

`<position>`

Moves the center of the circle. May be a `<length>`, or a `<percentage>`, or a values such as `left`. The `<position>` value defaults to center if omitted.

- `ellipse()`

Defines an ellipse using two radii and a position.

An ellipse is essentially a squashed circle and so ellipse() acts in a very similar way to circle() except that we have to specify two radii x and y.

```
<ellipse()> =
  ellipse( <radial-size>? [ at <position> ]? )

<radial-size> =
  <length-percentage [0,∞]>{2}

<position> =
  [ left | center | right | top | bottom | <length-percentage> ]  |
  [ left | center | right ] && [ top | center | bottom ]  |
  [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]  |
  [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ]

<length-percentage> =
  <length>      |
  <percentage>
```

`<radial-size>`

Two radii, x and y in that order. These may be a `<length>`, or a `<percentage>`.

`<position>`

Moves the center of the ellipse. May be a `<length>`, or a `<percentage>`, or a values such as left. The `<position>` value defaults to center if omitted.

- `path()`

Defines a shape using an SVG path definition.

```
  <path()> =
    path(<string> )
```

`path()`

The `path()` function takes [SVG path string](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Attribute/d) as argument.

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>view</>} inherited="no" animatable="no" />

## Difference with the Web

1. `inset()` function accepts `super-ellipse` as corner shape.
2. `polygon()` function is not supported.
3. `<clip-rule>` for `path()` function is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.clip-path`

**Specifications:**
- [https://drafts.fxtf.org/css-masking/#the-clip-path](https://drafts.fxtf.org/css-masking/#the-clip-path)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Clay macOS | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/color.md
---

<APISummary />

## Introduction

The `color` CSS property sets the foreground [`color value`](/api/css/data-type/color.md) of an element's text

## Examples

**This is an example below:  css-api**

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

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

const Color = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="container text2 font_style">Hello World</text>
        <text className="container text3 font_style">Hello World</text>
        <text className="container text4 font_style">Hello World</text>
        <text className="container text5 font_style">Hello World</text>
        <text className="container text6 font_style">Hello World</text>
        <text className="container text7 font_style">Hello World</text>
        <text className="container text8 font_style">Hello World</text>
        <text className="container text9 font_style">Hello 😄 😄 World</text>
      </view>
    </scroll-view>
  );
};

root.render(<Color />);

```



## Syntax

```css
/* <named-color> values */
color: red;
color: orange;
color: tan;

/* <hex-color> values */
color: #090;
color: #009900;
color: #090a;
color: #009900aa;

/* <rgb()> values */
color: rgb(34, 12, 64, 0.6);
color: rgba(34, 12, 64, 0.6);
color: rgb(34 12 64 / 0.6);
color: rgba(34 12 64 / 0.3);
color: rgb(34 12 64 / 60%);
color: rgba(34.6 12 64 / 30%);

/* <hsl()> values */
color: hsl(30, 100%, 50%, 0.6);
color: hsla(30, 100%, 50%, 0.6);
color: hsl(30 100% 50% / 0.6);
color: hsla(30 100% 50% / 0.6);
color: hsl(30 100% 50% / 60%);
color: hsla(30.2 100% 50% / 60%);
```

### Values

- [`<color>`](/api/css/data-type/color.md)

- [`<gradient>`](/api/css/data-type/gradient.md)

## Formal definition


<PropertyDefinition initialValue={<>transparent</>} appliesTo={<>text</>} inherited="no" animatable="yes" />

## Formal syntax

```
<color> | <gradient>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/column-gap.md
---

<APISummary />

## Introduction

The `column-gap`/`grid-column-gap` CSS property sets the size of the gap (gutter) between an element's columns in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) and grid layout.

For compatibility, `column-gap` or `grid-column-gap` can be used both.

## Examples

**This is an example below:  css-api**

**Entry:** `src/column-gap`
**Bundle:** `dist/column-gap.lynx.bundle`

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

const ColumnGap = () => {
  const flexContainerStyle = {
    display: "flex" as const,
    flexWrap: "wrap" as const,
    columnGap: "15px",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    marginBottom: "100rpx" as const,
  };

  const gridContainerStyle = {
    display: "grid" as const,
    columnGap: "10px",
    gridTemplateColumns: "1fr 1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>using column-gap in flex layout</text>
      <view style={flexContainerStyle}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
        <text className="item">SIX</text>
        <text className="item">SEVEN</text>
        <text className="item">EIGHT</text>
        <text className="item">NINE</text>
        <text className="item">TEN</text>
      </view>

      <text style={titleStyle}>using column-gap in grid layout</text>
      <view style={gridContainerStyle}>
        <text className="item2">ONE</text>
        <text className="item2">TWO</text>
        <text className="item2">THREE</text>
        <text className="item2">FOUR</text>
        <text className="item2">FIVE</text>
        <text className="item2">SIX</text>
        <text className="item2">SEVEN</text>
        <text className="item2">EIGHT</text>
        <text className="item2">NINE</text>
        <text className="item2">TEN</text>
      </view>
    </>
  );
};

root.render(<ColumnGap />);

```



## Syntax

```css
/* <length> values */
column-gap: 20px;
column-gap: 1em;

/* <percentage> value */
column-gap: 10%;

/* calc() values */
column-gap: calc(10% + 20px);
```

### Values

- `<length>`

Is the width of the gutter separating the columns.

- `<percentage>`

The size of the gap between columns, defined as a `percentage`. The `percentage` property's value must be non-negative.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>0</code>
  </>
}
  appliesTo={<>flex containers, grid containers</>}
  inherited="no"
  animatable="no"
  percentages={<>refer to row dimension of its own content area</>}
/>

## Formal syntax

```
column-gap = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- `normal` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.column-gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/column-gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/column-gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |

**Description:** <code>column-gap</code>




---
url: /api/css/properties/css-variable.md
---

# Custom properties (`--*`): CSS variables

<APISummary />

## Introduction

CSS variables, are defined with a specific syntax (e.g., `--main-color: black;`) and their values are accessed using the`var()`function (e.g., `color: var(--main-color);`). Custom properties store a value in one place and allow it to be referenced in multiple other places throughout the stylesheet, promoting reusability and maintainability.

## Examples

**This is an example below:  css**

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

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

export default function App() {
  const [isDark, setIsDark] = useState(false);
  const [useJS, setUseJS] = useState(false);
  const [showError, setShowError] = useState(false);
  const themeClass = isDark ? "theme-dark" : "theme-light";

  const toggleTheme = () => {
    if (useJS) {
      setShowError(true);
      setTimeout(() => setShowError(false), 3000);
      return;
    }

    setIsDark(prev => !prev);
  };

  const toggleThemeByJS = () => {
    setUseJS(true);
    const rootElement = lynx.getElementById("root");
    const newTheme = isDark ? "light" : "dark";

    if (rootElement) {
      if (isDark) {
        rootElement.setProperty({
          "--bg-primary": "#ffffff",
          "--bg-secondary": "#f5f5f5",
          "--text-primary": "#1a1a1a",
          "--text-secondary": "#666666",
          "--shadow": "rgba(0, 0, 0, 0.1)",
        });
      } else {
        rootElement.setProperty({
          "--bg-primary": "#2d2d2d",
          "--bg-secondary": "#1a1a1a",
          "--text-primary": "#ffffff",
          "--text-secondary": "#cccccc",
          "--shadow": "rgba(0, 0, 0, 0.3)",
        });
      }
      setIsDark(prev => !prev);
    }
  };

  return (
    <view id="root" className={themeClass}>
      <view className="container">
        <view className="theme-switchers">
          <view className="theme-card" bindtap={toggleTheme}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme by className</text>
          </view>
          <view className="theme-card" bindtap={toggleThemeByJS}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme through JS</text>
          </view>
        </view>
        <view className="content-cards">
          <view className="card">
            <text className="card-title">Card Sample 1</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 2</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 3</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 4</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
        </view>
      </view>
      {showError && (
        <view className="error-message-container">
          <text className="error-message">
            Cannot change variables through the class after modifying them in JS!
          </text>
        </view>
      )}
    </view>
  );
}

root.render(<App />);

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

```



## Syntax

```css
/* Declare css variables */
--somekeyword: left;
--somecolor: #0000ff;

/* Reference css variables */
background: var(--somecolor);
```

## Basic Usage

### Declaration

CSS Variable is a property whose name starts with two hyphens (`-`), such as `--foo`, which can be referenced with `var()` after it is defined.

```css
:root {
  --main-bg-color: yellow;
}

.two {
  --main-height: 200px;
  color: white;
  background-color: black;
  width: 100%;
  height: 100%;
}
```

You can delcare CSS variables in `style` attribute as well{/* 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 | - |




---
url: /api/css/properties/direction.md
---

<APISummary />

## Introduction

The `direction` CSS property sets the direction of text. Use `rtl` for languages written from right to left (like Hebrew or Arabic), and `ltr` for those written from left to right (like English and most other languages).

## Examples

**This is an example below:  css-api**

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

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

const Direction = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro">rtl|ltr</text>
      </view>
      <text>current: {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<Direction />);

```



## Syntax

```css
direction: normal;
direction: ltr;
direction: rtl;
```

### Values

- `normal`

  **Default value**.

  The [`text-align:start`](/api/css/properties/text-align.md) will align the text according to the direction of text content and the direction of text will be inferred from the text content. All other behaviors are same as `ltr`.

  For example:
  For:

  ```html
  <text> abc 1234 </text>
  ```

  The text will be left aligned. And the direction of the will be left to right.

  For:

  ```html
  <text> العاشر ليونيكود 1234</text>
  ```

  The text will be right aligned. And the direction of the will be right to left.

- `ltr`

  Text direction will be left-to-right, the horizontal logical properties "inline-start"(e.g. margin-inline-start) will be mapped to "left", and "inline-end" will be mapped to "right".

- `rtl`

  Text direction will be right-to-left, the horizontal logical properties "inline-start"(e.g. margin-inline-start) will be mapped to "right", and "inline-end" will be mapped to "left".

- `lynx-rtl` <Deprecated />

  Not recommended. **lynx only, designed for make ltr only pages compatible for rtl**, Text direction will be right-to-left, properties "left", "inline-start" (e.g. margin-left) will be mapped to right, and "right", "inline-end" will be mapped to "left".

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>normal</code>
  </>
}
  appliesTo={<>all elements</>}
  inherited="yes"
/>

## Formal syntax

```
direction = normal | ltr | rtl
```

## Difference with the web

- Value `normal`, `lynx-rtl` are introduced to improve page compatibility for `rtl`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.direction`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | direction:rtl is as powerful as direction:lynx-rtl; ⚠️ Partial implementation |




---
url: /api/css/properties/display.md
---

<APISummary />

## Introduction

In Lynx, the `display` only determines the internal display type of the element (how to layout the child elements), and does not determine the external display type (whether the element is considered a [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content) or an [inline-level element](https://developer.mozilla.org/en-US/docs/Glossary/Inline-level_content)).

Lynx does not have [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout) and does not support the `display: block/inline` syntax. All Lynx elements are [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content), except for the elements inside the `<text>` component.

:::info
[Linear layout](/guide/ui/layout/linear-layout.md) is the default layout for elements in Lynx. You can set `defaultDisplayLinear: false` in the project configuration to change the default layout to \[flexible box layout].
:::

## Examples

**This is an example below:  css-api**

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

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

const Display = () => {
  const fixedAreaStyle = {
    width: "50%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text>flex</text>
        <view className="container" style={{ display: "flex" }}>
          <text className="item">1</text>
          <text className="item">2</text>
        </view>

        <text>linear</text>
        <view className="container" style={{ display: "linear", linearOrientation: "horizontal" }}>
          <text className="item">1</text>
          <text className="item">2</text>
        </view>

        <text>relative</text>
        <view className="container" style={{ display: "relative" }}>
          <text
            className="item"
            style={{
              // @ts-expect-error TODO(types): Support relativeId in `@lynx-js/types`
              relativeId: "1",
            }}
          >
            1
          </text>
          <text
            className="item"
            style={{
              // @ts-expect-error TODO(types): Support relativeRightOf in `@lynx-js/types`
              relativeRightOf: "1",
            }}
          >
            2
          </text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Display />);

```



## Syntax

```css
display: flex;
display: none;
display: linear;
display: relative;
display: grid;
```

### Values

- `flex`

  See more in [flexible box layout](/guide/ui/layout/flexible-box-layout.md).

- `linear`

  [linear layout](/guide/ui/layout/linear-layout.md) is the default Layout model developed by Lynx. It has best **performance** in all types of layout in Lynx.

  :::info
  `<scroll-view>` is forced to be a linear layout, in which case `<scroll-view>` is formatted as a normal linear view. Both the alignment attribute and [linear-weight](/api/css/properties/linear-weight.md) take effect. And `scroll-x`/`scroll-y` will change the main axis to horizontal and vertical respectively. (The actual conversion is determined by whether to set `scroll-x`/`scroll-y`.)
  :::

- `none`

  Element and its descents will be resized to 0x0.

  :::info
  If the parent element of the `<text>` element is set to `display:none` and the `<text>` element is still rendered visible, please add [`overflow:hidden`](/api/css/properties/overflow.md) to the corresponding parent element. We will fix this issue in the future.
  :::

- `grid`

  Element will layout according to the grid layout layout model.

- `relative`

  Relative layout is a Layout model developed by Lynx.

  Element will layout according to the relative layout model. Relative layout is a layout that displays children in relative positions, where each view's position can be specified relative to sibling elements (for example, to the left or below another view) or relative to the parent's area (e.g. align at bottom, left or center).

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>linear</code>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
/>

## Formal syntax

```
display = none | linear | flex | grid | relative
```

## Difference with the web

- In Lynx, the `display` only determines the internal display type of the element (how to layout the child elements), and does not determine the external display type (whether the element is considered a [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content) or an [inline-level element](https://developer.mozilla.org/en-US/docs/Glossary/Inline-level_content)).
- [relative layout](/guide/ui/layout/relative-layout.md) and [linear layout](/guide/ui/layout/linear-layout.md) are Layout models developed by Lynx.
- Lynx does not have [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout) and does not support the `display: block/inline` syntax. All Lynx elements are [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content), except for the elements inside the `<text>` component.
- `inline-block`, `inline-flex`, `inline-grid` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.display`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/display](https://developer.mozilla.org/zh-CN/docs/Web/CSS/display)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |


## FAQ

- `<scroll-view>` is forced to be a linear layout, in which case `<scroll-view>` is formatted as a normal linear view. Both the alignment attribute and [`linear-weight`](/api/css/properties/linear-weight.md) take effect. And `scroll-x`/`scroll-y` will change the main axis to horizontal and vertical respectively. (The actual conversion is determined by whether to set `scroll-x`/`scroll-y`.)



---
url: /api/css/properties/filter.md
---

<APISummary />

## Introduction

The `filter` CSS property applies graphical effects like blur or color shift to an element.

:::info

Currently only the `blur`, `grayscale`, `brightness`, `contrast` and `saturate` functions are supported.

If you use `opacity`, you can directly set properties for the view, [link](/api/css/properties/opacity.md)

Views with the `grayscale` attribute added on Android will create off-screen buffer on the GPU. A large number of off-screen buffer will cause rendering performance to decrease. It is recommended to replace `filter: grayscale(0)` with `filter: none` to remove off-screen caching when grayscale is not needed.

:::

:::info Android blur (OS Version \< 12)

When using blur, you can add `blur-sampling` property (an int value) to the node to set the downsampling ratio to improve performance.

Setting the blur area may cause performance issues if content is updated all the time.

For higher blur efficiency, it is recommended that the actual size of the blur-radius should not exceed 25, that is, the maximum write 25ppx or 25/density px.

:::

## Examples

**This is an example below:  css-api**

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

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";
import lynxImage from "../../resource/bg_flower.gif";

const Filter = () => {
  const blurStyle = {
    filter: "blur(10px)",
  };

  const grayscaleStyle = {
    filter: "grayscale(100%)",
  };

  const brightnessStyle = {
    filter: "brightness(0.3)",
  };

  const contrastStyle = {
    filter: "contrast(0.5)",
  };

  const saturateStyle = {
    filter: "saturate(0.7)",
  };

  const imageStyle = {
    width: "100px",
    height: "140px",
  };

  return (
    <scroll-view className="w-100 h-100" scroll-orientation="vertical">
      <view style={blurStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={grayscaleStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={brightnessStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={contrastStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={saturateStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
    </scroll-view>
  );
};

root.render(<Filter />);

```



## Syntax

```css
filter: grayscale(100%);
filter: blur(5px);
filter: brightness(0.6);
filter: contrast(0.7);
filter: saturate(0.8);
```

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal Syntax

```
filter = <filter-function>

<filter-function> =
  <blur()>         |
  <grayscale()>    |

<blur()> =
  blur( <length>? )

<grayscale()> =
  grayscale( [ <percentage> ]? )

<brightness()> =
  brightness( [ <number> | <percentage> ]? )

<contrast()> =
  contrast( [ <number> | <percentage> ]? )

<saturate()> =
  saturate( [ <number> | <percentage> ]? )

```

## Differences from the Web

- Only one filter function is allowed per declaration
- Only supports `blur`, `grayscale`, `brightness`, `contrast` and `saturate` functions

## Compatibility

**Compatibility Table**
**Query:** `css.properties.filter`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/filter](https://developer.mozilla.org/zh-CN/docs/Web/CSS/filter)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |


**Error:** No compatibility data found for `css.properties.filter-properties`


---
url: /api/css/properties/flex-basis.md
---

<APISummary />

## Introduction

The `flex-basis` CSS property sets the initial main size of a flex item. In case both `flex-basis` (other than `auto`) and [`width`](/api/css/properties/width.md) or [`height`](/api/css/properties/height.md) in case of [`flex-direction: column`](/api/css/properties/flex-direction.md) are set for an element, `flex-basis` has priority.

## Examples

**This is an example below:  css-api**

**Entry:** `src/flex-basis`
**Bundle:** `dist/flex-basis.lynx.bundle`

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

const FlexBasis = () => {
  const itemStyle = {
    marginLeft: "5px",
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexGrow: 1,
  };

  const autoStyle = {
    flexBasis: "auto" as const,
    backgroundColor: "rgba(255,0,200,0.2)" as const,
    flexGrow: 1,
  };

  const zeroPxStyle = {
    flexBasis: "0px",
    backgroundColor: "rgba(255,0,200,0.2)" as const,
    flexGrow: 1,
  };

  const px300Style = {
    flexBasis: "300px",
    backgroundColor: "rgba(255,0,200,0.2)" as const,
    flexGrow: 1,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view style={autoStyle}>
            <text>flex-basis:auto</text>
          </view>
          <view style={itemStyle}>
            <text>Item Two</text>
          </view>
          <view style={itemStyle}>
            <text>Item Three</text>
          </view>
        </view>

        <view className="container">
          <view style={zeroPxStyle}>
            <text>flex-basis:0px</text>
          </view>
          <view style={itemStyle}>
            <text>Item Two</text>
          </view>
          <view style={itemStyle}>
            <text>Item Three</text>
          </view>
        </view>

        <view className="container">
          <view style={px300Style}>
            <text>flex-basis:300px</text>
          </view>
          <view style={itemStyle}>
            <text>Item Two</text>
          </view>
          <view style={itemStyle}>
            <text>Item Three</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexBasis />);

```



## Syntax

```css
/* Specify <'width'> */
flex-basis: 10em;
flex-basis: 3px;
flex-basis: 50%;
flex-basis: auto;
```

### Values

- `auto`

  **Default value**. refer to [`width`](/api/css/properties/width.md) and [`height`](/api/css/properties/height.md).

- `<length>`

  sets an absolute value.

- `<percentage>`

  sets a percentage of the width or height of a containing block's content area.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>flex items</>}
  inherited="no"
  animatable="yes"
  percentages={<>refer to containing block's content area</>}
/>

## Formal syntax

```
flex-basis = auto | <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- Not under [`box-sizing`](/api/css/properties/box-sizing.md) influence.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-basis`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-basis](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-basis)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** <code>flex-basis</code>




---
url: /api/css/properties/flex-direction.md
---

<APISummary />

## Introduction

The `flex-direction` CSS property sets how flex items are placed in the flex container defining the main axis and the direction.

## Examples

**This is an example below:  css-api**

**Entry:** `src/flex-direction`
**Bundle:** `dist/flex-direction.lynx.bundle`

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

const FlexDirection = () => {
  const greenStyle = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexGrow: 1,
  };

  const blueStyle = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexGrow: 1,
  };

  const redStyle = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexGrow: 1,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="row">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>

        <view className="row-reverse">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>

        <view className="container column">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>

        <view className="container column-reverse">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexDirection />);

```



Note that the values `row` and `row-reverse` are affected by the directionality of the flex container. If its [`dir`](/api/css/properties/direction.md) attribute is `ltr`, `row` represents the horizontal axis oriented from the left to the right, and `row-reverse` from the right to the left; if the `dir` attribute is `rtl`, `row` represents the axis oriented from the right to the left, and `row-reverse` from the left to the right.

## Syntax

```css
/* The direction text is laid out in a line */
flex-direction: row;

/* Like <row>, but reversed */
flex-direction: row-reverse;

/* The direction in which lines of text are stacked */
flex-direction: column;

/* Like <column>, but reversed */
flex-direction: column-reverse;
```

### Values

- `row`

  **Default value**. The flex container's main-axis is defined to be the same as the text direction. The main-start and main-end points are the same as the content direction.

- `row-reverse`

  Behaves the same as `row` but the main-start and main-end points are opposite to the content direction.

- `column`

  The flex container's main-axis is the same as the vertical. The main-start and main-end points are the same as the before and after points of the writing-mode.

- `column-reverse`

  Behaves the same as `column` but the main-start and main-end are opposite to the content direction.

## Formal definition


<PropertyDefinition initialValue={<>row</>} appliesTo={<>flex containers</>} inherited="no" />

## Formal syntax

```
flex-direction =
  row             |
  row-reverse     |
  column          |
  column-reverse
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-direction`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-direction](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-direction)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-flow.md
---

<APISummary />

## Introduction

This property is a shorthand for the CSS properties: [`flex-direction`](/api/css/properties/flex-direction.md) and [`flex-wrap`](/api/css/properties/flex-wrap.md), specifies the direction of a flex container, as well as its wrapping behavior.

## Examples

**This is an example below:  css-api**

**Entry:** `src/flex-flow`
**Bundle:** `dist/flex-flow.lynx.bundle`

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

const FlexFlow = () => {
  const flowStyle = {
    flexFlow: "row wrap" as const,
  };

  const flow2Style = {
    flexDirection: "row" as const,
    flexWrap: "wrap" as const,
  };

  const item1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 0,
    width: "50%",
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item4Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text>flex-flow: row wrap</text>
      <view className="container" style={flowStyle}>
        <view className="height" style={item1Style}>
          <text>Item One</text>
        </view>
        <view className="height" style={item2Style}>
          <text>Item Two</text>
        </view>
        <view className="height" style={item3Style}>
          <text>Item Three</text>
        </view>
        <view className="height" style={item4Style}>
          <text>Item Four</text>
        </view>
      </view>
      <text>flex-direction: row; flex-wrap: wrap</text>
      <view className="container" style={flow2Style}>
        <view className="height" style={item1Style}>
          <text>Item One</text>
        </view>
        <view className="height" style={item2Style}>
          <text>Item Two</text>
        </view>
        <view className="height" style={item3Style}>
          <text>Item Three</text>
        </view>
        <view className="height" style={item4Style}>
          <text>Item Four</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexFlow />);

```



## Syntax

```css
/* flex-flow: <'flex-direction'> */
flex-flow: row;
flex-flow: row-reverse;
flex-flow: column;
flex-flow: column-reverse;

/* flex-flow: <'flex-wrap'> */
flex-flow: nowrap;
flex-flow: wrap;
flex-flow: wrap-reverse;

/* flex-flow: <'flex-direction'> and <'flex-wrap'> */
flex-flow: row nowrap;
flex-flow: column wrap;
flex-flow: column-reverse wrap-reverse;
```

### Values

This property is a shorthand for the following CSS properties: [`flex-direction`](/api/css/properties/flex-direction.md) and [`flex-wrap`](/api/css/properties/flex-wrap.md)。

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    as each of the properties of the shorthand: <br />
    <ul style={{ listStyleType: 'disc', paddingLeft: '1.5rem' }}>
      <li>flex-direction: row</li>
      <li>flex-wrap: nowrap</li>
    </ul>
  </>
}
  appliesTo={<>flex containers</>}
  inherited="no"
/>

## Formal syntax

```
flex-flow =
  <'flex-direction'>  ||
  <'flex-wrap'>

<flex-direction> =
  row             |
  row-reverse     |
  column          |
  column-reverse

<flex-wrap> =
  nowrap        |
  wrap          |
  wrap-reverse
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-flow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-flow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-flow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-grow.md
---

<APISummary />

## Introduction

The `flex-grow` CSS property sets the flex grow factor, which specifies how much of the flex container's remaining space should be assigned to the flex item's main size.

When the flex-container's main size is larger than the combined main sizes of the flex items, the extra space is distributed among the flex items, with each item growth being their growth factor value as a proportion of the sum total of all the container's items' flex grow factors.

The main size is either width or height of the item which is dependent on the [`flex-direction`](/api/css/properties/flex-direction.md) value.

`flex-grow` is used alongside the other flex properties [`flex-shrink`](/api/css/properties/flex-shrink.md) and [`flex-basis`](/api/css/properties/flex-basis.md), and normally defined using the [flex](/api/css/properties/flex.md) shorthand to ensure all values are set.

## Examples

**This is an example below:  css-api**

**Entry:** `src/flex-grow`
**Bundle:** `dist/flex-grow.lynx.bundle`

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

const FlexGrow = () => {
  const grow1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexGrow: 1,
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexGrow: 0,
    marginLeft: "10px",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexGrow: 0,
    marginLeft: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view className="height" style={grow1Style}>
            <text>flex-grow:1</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexGrow />);

```



## Syntax

```css
/* <number> values */
flex-grow: 3;
flex-grow: 0.6;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid, **Defaults** to `0`。

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>flex items</>} inherited="no" animatable="yes" />

## Formal syntax

```
flex-grow =
  <number [0,∞]>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-grow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-grow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-grow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-shrink.md
---

<APISummary />

## Introduction

Defines the shrink factor of the flex element on the main axis. After the flex container layout elements, if there is an element overflow, the corresponding element will be scaled according to the element's zoom factor ratio to ensure that the element will not overflow the container.

## Examples

**This is an example below:  css-api**

**Entry:** `src/flex-shrink`
**Bundle:** `dist/flex-shrink.lynx.bundle`

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

const FlexShrink = () => {
  const shrink1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 1,
  };

  const shrink2Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 2,
    marginLeft: "10px",
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
    width: "30%",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
    width: "40%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view className="height" style={shrink1Style}>
            <text>flex-shrink:1</text>
          </view>
          <view className="height" style={shrink2Style}>
            <text>flex-shrink:2</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexShrink />);

```



## Syntax

```css
/* <number> values */
flex-shrink: 2;
flex-shrink: 0;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid. Defaults to `1`.

## Formal definition


<PropertyDefinition initialValue={<>1</>} appliesTo={<>flex items</>} inherited="no" />

## Formal syntax

```
flex-shrink =
  <number [0,∞]>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-shrink`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-shrink](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-shrink)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-wrap.md
---

<APISummary />

## Introduction

The `flex-wrap` CSS property sets whether flex items are forced onto one line or can wrap onto multiple lines. If wrapping is allowed, it sets the direction that lines are stacked.

## Examples

**This is an example below:  css-api**

**Entry:** `src/flex-wrap`
**Bundle:** `dist/flex-wrap.lynx.bundle`

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

const FlexWrap = () => {
  const item1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 0,
    width: "50%",
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item4Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <text>flex-wrap:nowrap</text>
        <view className="container nowrap">
          <view className="height" style={item1Style}>
            <text>Item One</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
          <view className="height" style={item4Style}>
            <text>Item Four</text>
          </view>
        </view>

        <text>flex-wrap:nowrap</text>
        <view className="container wrap">
          <view className="height" style={item1Style}>
            <text>Item One</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
          <view className="height" style={item4Style}>
            <text>Item Four</text>
          </view>
        </view>

        <text>flex-wrap:wrap-reverse</text>
        <view className="container wrap-reverse">
          <view className="height" style={item1Style}>
            <text>Item One</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
          <view className="height" style={item4Style}>
            <text>Item Four</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexWrap />);

```



## Syntax

```css
flex-wrap: nowrap; /* Default value */
flex-wrap: wrap;
flex-wrap: wrap-reverse;
```

### Values

- `nowrap`

  **Default value**. The flex items are laid out in a single line which may cause the flex container to overflow. The cross-start is either equivalent to start or before depending on the [`flex-direction`](/api/css/properties/flex-direction.md) value.

- `wrap`

  The flex items break into multiple lines. The cross-start is either equivalent to start or before depending [`flex-direction`](/api/css/properties/flex-direction.md) value and the cross-end is the opposite of the specified cross-start.

- `wrap-reverse`

  Behaves the same as `wrap` but cross-start and cross-end are permuted.

## Formal definition


<PropertyDefinition initialValue={<>nowrap</>} appliesTo={<>flex containers</>} inherited="no" />

## Formal syntax

```
flex-wrap =
  nowrap        |
  wrap          |
  wrap-reverse
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-wrap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-wrap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-wrap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex.md
---

<APISummary />

## Introduction

The `flex` CSS shorthand property sets how a flex item will grow or shrink to fit the space available in its flex container. This property is a shorthand for the following CSS properties: [`flex-grow`](/api/css/properties/flex-grow.md), [`flex-shrink`](/api/css/properties/flex-shrink.md), [`flex-basis`](/api/css/properties/flex-basis.md).

## Examples

**This is an example below:  css-api**

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

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

const Flex = () => {
  const firstBoxStyle = {
    flex: "1",
    backgroundColor: "rgba(255,0,200,0.2)",
  };

  const secondBoxStyle = {
    flex: "1 30px",
    marginLeft: "5px",
    backgroundColor: "rgba(0,0,255,0.2)",
  };

  const thirdBoxStyle = {
    flex: "2 1 auto",
    marginLeft: "5px",
    backgroundColor: "rgba(0,0,255,0.2)",
  };

  return (
    <view className="container">
      <view className="height" style={firstBoxStyle}>
        <text>flex:1;</text>
      </view>
      <view className="height" style={secondBoxStyle}>
        <text>flex:1 30px;</text>
      </view>
      <view className="height" style={thirdBoxStyle}>
        <text>flex:2 1 auto;</text>
      </view>
    </view>
  );
};

root.render(<Flex />);

```



## Syntax

```css
flex: none;
flex: auto;

/* One value, unitless number: flex-grow
flex-basis is then equal to 0. */
flex: 2;

/* One value, width/height: flex-basis */
flex: 10em;
flex: 30%;

/* Two values: flex-grow | flex-basis */
flex: 1 30px;

/* Two values: flex-grow | flex-shrink */
flex: 2 2;

/* Three values: flex-grow | flex-shrink | flex-basis */
flex: 2 2 10%;
```

The `flex` property may be specified using one, two, or three values.

- **One-value syntax**:

  - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-grow>`](/api/css/properties/flex-grow.md), then the shorthand expands to `flex: <flex-grow> 1 0`.
  - A valid [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) or key word `auto`, it will be used as the value of [`<flex-basis>`](/api/css/properties/flex-basis.md), then the shorthand expands to `flex: 1 1 <flex-basis>`.

- **Two-value syntax**:

  - The first value must be a valid value for [`<flex-grow>`](/api/css/properties/flex-grow.md).
  - The second value must be one of:
    - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-shrink>`](/api/css/properties/flex-shrink.md), then the shorthand expands to `flex: <flex-grow> <flex-shrink> 0`.
    - A valid [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) or key word `auto`, it will be used as the value of [`<flex-basis>`](/api/css/properties/flex-basis.md), then the shorthand expands to `flex: <flex-grow> 1 <flex-basis>`.

- Three-value syntax: the values must be in the following order:
  - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-grow>`](/api/css/properties/flex-grow.md).
  - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-shrink>`](/api/css/properties/flex-shrink.md).
  - A valid [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) or key word `auto`, it will be used as the value of [`<flex-basis>`](/api/css/properties/flex-basis.md).

### Values

- `0 1 auto`

  **Default value**. The item is sized according to its width and height properties. It shrinks to its minimum size to fit the container, but does not grow to absorb any extra free space in the flex container.

- `auto`

  The item is sized according to its width and height properties, but grows to absorb any extra free space in the flex container, and shrinks to its minimum size to fit the container. This is equivalent to setting "`flex: 1 1 auto`".

- `none`

  The item is sized according to its width and height properties. It is fully inflexible: it neither shrinks nor grows in relation to the flex container. This is equivalent to setting "`flex: 0 0 auto`".

- `<flex-grow>`

  Defines the [`flex-grow`](/api/css/properties/flex-grow.md) of the flex item. Negative values are considered invalid. Defaults to 1 when omitted.

- `<flex-shrink>`

  Defines the [`flex-shrink`](/api/css/properties/flex-shrink.md) of the flex item. Negative values are considered invalid. Defaults to 1 when omitted.

- `<flex-basis>`

  Defines the [`flex-basis`](/api/css/properties/flex-basis.md) of the flex item. A preferred size of 0 must have a unit to avoid being interpreted as a flexibility. Defaults to `auto` when omitted. (initial is auto)

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    as each of the properties of the shorthand: <br />
    <ul style={{ listStyleType: 'disc', paddingLeft: '1.5rem' }}>
      <li>
        <code>flex-grow: 0</code>
      </li>
      <li>
        <code>flex-shrink: 1</code>
      </li>
      <li>
        <code>flex-basis: auto</code>
      </li>
    </ul>
  </>
}
  appliesTo={<>flex items</>}
  inherited="no"
/>

## Formal syntax

```
flex =
  none                                                |
  [ <'flex-grow'> <'flex-shrink'>? || <'flex-basis'> ]

<flex-grow> =
  <number [0,∞]>

<flex-shrink> =
  <number [0,∞]>

<flex-basis> = <'width'>

<width> =
  auto                                      |
  <length-percentage [0,∞]>                 |
  max-content                               |
  fit-content( <length-percentage [0,∞]> )

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-family.md
---

<APISummary />

## Introduction

The `font-family` CSS property specifies a prioritized list of one or more font family names and/or generic family names for the selected element.

## Examples

**This is an example below:  css-api**

**Entry:** `src/font-family`
**Bundle:** `dist/font-family.lynx.bundle`

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

const FontFamily = () => {
  const fontStyle = {
    fontFamily: "icon-font",
    fontSize: "20px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={{ flexDirection: "column" }} className="container">
        <text style={fontStyle}>
          {"base64编码的字体\n&#xe61c;&#xe61d;&#xe61e;&#xe61f;&#xe620;&#xe621;&#xe622;&#xe623;&#xe624;"}
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<FontFamily />);

```



## Syntax

```css
font-family: font1, font2;
```

## Formal definition


<PropertyDefinition initialValue={<></>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal syntax

```
font-family =
  [ <string> | <custom-ident> ]#
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-family`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-family](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-family)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-feature-settings.md
---

<APISummary />

## Introduction

The `font-feature-settings` CSS property is used to control advanced typographic features in OpenType fonts.

## Examples

**This is an example below:  css-api**

**Entry:** `src/font-feature-settings`
**Bundle:** `dist/font-feature-settings.lynx.bundle`

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

const FontFeatureSettings = () => {
  return (
    <view style={{ display: "linear" }}>
      <text>normal</text>
      <text className="variable-font-normal">1234567890</text>
      <text>font-feature-settings:'onum'</text>
      <text className="variable-font-normal font-feature-settings">1234567890</text>
    </view>
  );
};

root.render(<FontFeatureSettings />);

```



## Syntax

```css
font-feature-settings: 'onum';
```

## Formal Definition


<PropertyDefinition initialValue="normal" appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal Syntax

```
font-feature-settings =
  normal                |
  <feature-tag-value>#

<feature-tag-value> =
  <opentype-tag> [ <integer [0,∞]> | on | off ]?

<opentype-tag> =
  <string>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-feature-settings`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-feature-settings](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-feature-settings)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | iOS supports commonly used and registered OpenType tags: hlig, clig, c2sc, c2pc, smcp, pcap, ss01-ss20, onum, lnum, pnum, tnum, frac, afrc, zero, ordn, sups, subs, case, titl, sinf.; ⚠️ Partial implementation |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-optical-sizing.md
---

<APISummary />

## Introduction

The `font-optical-sizing` CSS property sets whether text rendering is optimized for viewing at different sizes.

## Examples

**This is an example below:  css-api**

**Entry:** `src/font-optical-sizing`
**Bundle:** `dist/font-optical-sizing.lynx.bundle`

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

const FontOpticalSizing = () => {
  return (
    <view style={{ display: "linear", width: "300px" }}>
      <text>normal</text>
      <text className="variable-font-normal">
        On this particular Thursday, something was moving quietly through the ionosphere many miles above the surface of
        the planet; several somethings in fact, several dozen huge yellow chunky slablike somethings, huge as office
        blocks, silent as birds.
      </text>
      <view style={{ height: "10px" }}></view>
      <text>font-optical-sizing: auto</text>
      <text className="variable-font-normal font-optical-sizing">
        On this particular Thursday, something was moving quietly through the ionosphere many miles above the surface of
        the planet; several somethings in fact, several dozen huge yellow chunky slablike somethings, huge as office
        blocks, silent as birds.
      </text>
    </view>
  );
};

root.render(<FontOpticalSizing />);

```



## Syntax

```css
font-optical-sizing: auto;
```

## Formal Definition


<PropertyDefinition initialValue="none" appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal Syntax

```
font-optical-sizing =
  auto | none
```

## Difference with Web

- Unlike the Web default value of `auto`, the default value in Lynx is `none`. The `font-optical-sizing` property is a supplement to the `font-variation-settings` property and the optical size variation axis is represented by `opsz` in `font-variation-settings`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-optical-sizing`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/CSS/font-optical-sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/font-optical-sizing)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-size.md
---

<APISummary />

## Introduction

`font-size` CSS property sets the size of the font. Changing the font size also updates the sizes of the font size-relative `<length>` units, such as em, ex, and so forth.

## Examples

**This is an example below:  css-api**

**Entry:** `src/font-size`
**Bundle:** `dist/font-size.lynx.bundle`

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

const FontSize = () => {
  const fontStyle = {
    fontSize: "30px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <text>hello lynx, default font size</text>
        <text style={fontStyle}>hello lynx, font size 30px</text>
      </view>
    </scroll-view>
  );
};

root.render(<FontSize />);

```



## Syntax

```css
/* <length> */
font-size: 12px;
font-size: 0.8em;

/* <percentage> */
font-size: 80%;
```

### Values

- `<length>` <br />
  Positive `<length>` value. For most font-relative units (such as em and ex), the font size is relative to the parent element's font size.

- `<percentage>` <br />
  A positive `<percentage>` value, relative to the parent element's font size.

## Formal definition


<PropertyDefinition initialValue={<>14px</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal syntax

```
font-size = <length> | <percentage>
```

## Difference with Web

- Only support `<length>` and `<percentage>`

- Default font-size is **14px** not **medium**.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-size`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-size](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-size)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-style.md
---

<APISummary />

## Introduction

Set the font style.

## Examples

**This is an example below:  css-api**

**Entry:** `src/font-style`
**Bundle:** `dist/font-style.lynx.bundle`

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

const FontStyle = () => {
  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <text>
          font-style: 无
        </text>

        <text style={{ fontStyle: "normal" }}>
          font-style: normal 普通
        </text>

        <text style={{ fontStyle: "italic" }}>
          font-style: italic 斜体
        </text>

        <text style={{ fontStyle: "oblique" }}>
          font-style: oblique 倾斜
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<FontStyle />);

```



## Syntax

```css
font-style: italic;
font-style: oblique;
font-style: normal;
```

### Values

- **`normal`**
  Selects a font that is classified as normal within a font-family.

- `italic`
  Selects a font that is classified as `italic`.

- `oblique`
  Selects a font that is classified as `oblique`.

## Formal definition


<PropertyDefinition initialValue={<>normal</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal syntax

```
font-style = normal | italic | oblique
```

## Difference with Web

- Only support `normal`, `oblique` and `italic`

- [mdn:font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-variation-settings.md
---

<APISummary />

## Introduction

The `font-variation-settings` CSS property provides low-level control over variable font characteristics by letting you specify the four letter axis names of the characteristics you want to vary along with their values.

## Examples

**This is an example below:  css-api**

**Entry:** `src/font-variation-settings`
**Bundle:** `dist/font-variation-settings.lynx.bundle`

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

const FontVariationSettings = () => {
  return (
    <view style={{ display: "linear" }}>
      <text>normal</text>
      <text className="variable-font-normal">1234567890</text>
      <text>font-variation-settings:'wght' 750</text>
      <text className="variable-font-normal font-variation-settings">1234567890</text>
    </view>
  );
};

root.render(<FontVariationSettings />);

```



## Syntax

```css
font-variation-settings: 'wght' 750;
```

## Formal Definition


<PropertyDefinition initialValue="normal" appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal Syntax

```
font-variation-settings =
  normal                        |
  [ <opentype-tag> <number> ]#

<opentype-tag> =
  <string>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-variation-settings`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-weight.md
---

<APISummary />

## Introduction

The `font-weight` CSS property sets the weight (or boldness) of the font. The weights available depend on the font-family that is currently set.

## Examples

**This is an example below:  css-api**

**Entry:** `src/font-weight`
**Bundle:** `dist/font-weight.lynx.bundle`

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

const FontWeight = () => {
  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={{ fontWeight: "100", fontSize: "30px" }}>font-weight: 100</text>
      <text style={{ fontWeight: "200", fontSize: "30px" }}>font-weight: 200</text>
      <text style={{ fontWeight: "300", fontSize: "30px" }}>font-weight: 300</text>
      <text style={{ fontWeight: "400", fontSize: "30px" }}>font-weight: 400</text>
      <text style={{ fontWeight: "500", fontSize: "30px" }}>font-weight: 500</text>
      <text style={{ fontWeight: "600", fontSize: "30px" }}>font-weight: 600</text>
      <text style={{ fontWeight: "700", fontSize: "30px" }}>font-weight: 700</text>
      <text style={{ fontWeight: "800", fontSize: "30px" }}>font-weight: 800</text>
    </scroll-view>
  );
};

root.render(<FontWeight />);

```



## Syntax

```css
/* Keyword values */
font-weight: normal;
font-weight: bold;

/* Numeric keyword values */
font-weight: 100;
font-weight: 200;
font-weight: 300;
font-weight: 400;
font-weight: 500;
font-weight: 600;
font-weight: 700;
font-weight: 800;
font-weight: 900;
font-weight: 1000;
```

### Values

- Default **normal** <br />
  Normal font weight. Same as `400`.

- `bold` <br />
  Bold font weight. Same as `700`

- `<number>` <br />
  A `<number>` value between 1 and 1000, inclusive. Higher numbers represent weights that are bolder than (or as bold as) lower numbers.

## Best Practices

- Do not using `font-weight` with `font-family`. Currently, lynx `font-family` is just a key-value mapping not a real 'family'. And using other font-weight may cause `font-family` not working.

## Formal definition


<PropertyDefinition initialValue={<>normal</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal syntax

```
<font-weight> = normal | bold | [100, 1000]
```

## Difference with Web

- Not support `border` and `lighter`

- Numeric types currently only support integer values from '100' to '1000'.

- The fallback logic of glyph mapping failure will vary on different platforms and system versions. In the worst case, the system default font may be fallback, resulting in the failure of custom fonts.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-weight`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-weight](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-weight)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/gap.md
---

<APISummary />

## Introduction

The `gap` CSS shorthand property sets the gaps (gutters) between rows and columns in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) and [grid layout](/guide/ui/layout/grid-layout.md).

This property is a shorthand for the following CSS properties: [`row-gap`](/api/css/properties/row-gap.md) and [`column-gap`](/api/css/properties/column-gap.md), this property is specified as a value for `row-gap` followed optionally by a value for `column-gap`. If `column-gap` is omitted, it's set to the same value as `row-gap`. `row-gap` and `column-gap` are each specified as a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md).

## Examples

**This is an example below:  css-api**

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

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

const Gap = () => {
  const flexContainerStyle = {
    display: "flex" as const,
    flexWrap: "wrap" as const,
    gap: "15px",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    marginBottom: "100rpx" as const,
  };

  const gridContainerStyle = {
    display: "grid" as const,
    gap: "10px",
    gridTemplateColumns: "1fr 1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>using gap in flex layout</text>
      <view style={flexContainerStyle}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
        <text className="item">SIX</text>
        <text className="item">SEVEN</text>
        <text className="item">EIGHT</text>
        <text className="item">NINE</text>
        <text className="item">TEN</text>
      </view>

      <text style={titleStyle}>using gap in grid layout</text>
      <view style={gridContainerStyle}>
        <text className="item2">ONE</text>
        <text className="item2">TWO</text>
        <text className="item2">THREE</text>
        <text className="item2">FOUR</text>
        <text className="item2">FIVE</text>
        <text className="item2">SIX</text>
        <text className="item2">SEVEN</text>
        <text className="item2">EIGHT</text>
        <text className="item2">NINE</text>
        <text className="item2">TEN</text>
      </view>
    </>
  );
};

root.render(<Gap />);

```



## Syntax

```css
/* One <length> value */
gap: 20px;
gap: 1em;

/* One <percentage> value */
gap: 16%;
gap: 100%;

/* Two <length> values */
gap: 20px 10px;
gap: 1em 0.5em;

/* One or two <percentage> values */
gap: 16% 100%;
gap: 21px 82%;

/* calc() values */
gap: calc(10% + 20px);
gap: calc(20px + 10%) calc(10% - 5px);
```

### Values

- `<length>`

  [`<length>`](/api/css/data-type/length.md) is the width of the gutter in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) or grid layout.

- `<percentage>`

  [`<percentage>`](/api/css/data-type/percentage.md) is the width of the gutter separating the lines, relative to the dimension of the element.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    as each of the properties of the shorthand: <br />
    <ul style={{ listStyleType: 'disc', paddingLeft: '1.5rem' }}>
      <li>
        <code>row-gap: 0</code>
      </li>
      <li>
        <code>column-gap: 0</code>
      </li>
    </ul>
  </>
}
  appliesTo={<>flex containers, grid containers</>}
  inherited="no"
  percentages={
  <>
    refer to corresponding dimension of the content area(e.g.,
    <code>row-gap</code> refer to column axis size)
  </>
}
/>

## Formal syntax

```
gap =
  <'row-gap'> <'column-gap'>?

<row-gap> = <length-percentage [0,∞]>

<column-gap> = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-auto-columns.md
---

<APISummary />

## Introduction

The `grid-auto-columns` CSS property specifies the size of an implicitly-created grid column track or pattern of tracks.

If a grid item is positioned into a column that is not explicitly sized by [`grid-template-columns`](/api/css/properties/grid-template-columns.md), implicit grid tracks are created to hold it. This can happen either by explicitly positioning into a column that is out of range, or by the auto-placement algorithm creating additional columns.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-auto-columns`
**Bundle:** `dist/grid-auto-columns.lynx.bundle`

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

const GridAutoColumns = () => {
  const Container1Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoColumns: "100px",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const Container2Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoColumns: "1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const item1Style = {
    gridColumnStart: "1",
    gridColumnEnd: "3",
  };

  const item2Style = {
    gridColumnStart: "2",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-auto-columns: 100px</text>
      <view style={Container1Style}>
        <text className="item" style={item1Style}>ONE</text>
        <text className="item" style={item2Style}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-auto-columns: 1fr</text>
      <view style={Container2Style}>
        <text className="item" style={item1Style}>ONE</text>
        <text className="item" style={item2Style}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridAutoColumns />);

```



## Syntax

```css
/* Keyword values */
grid-auto-columns: max-content;
grid-auto-columns: auto;

/* <length> values */
grid-auto-columns: 100px;

/* <percentage> values */
grid-auto-columns: 10%;
grid-auto-columns: 33.3%;

/* <flex> values */
grid-auto-columns: 0.5fr;
grid-auto-columns: 3fr;

/* minmax() values */
grid-auto-columns: minmax(100px, auto);
grid-auto-columns: minmax(max-content, 2fr);

/* fit-content() values */
grid-auto-columns: fit-content(400px);
grid-auto-columns: fit-content(20%);

/* multiple track-size values */
grid-auto-columns: 100px 150px 390px;
grid-auto-columns: 10% 33.3%;
grid-auto-columns: 0.5fr 3fr 1fr;
grid-auto-columns: 100px minmax(100px, auto) 10% 0.5fr fit-content(400px);
```

### Values

- `auto`

  **Default value**.

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `<length>`

  Is a non-negative length.

- `<percentage>`

  Is a non-negative `<percentage>` value relative to the inline size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `max(minimum, min(limit, max-content))`, where minimum represents an `auto` minimum (which is often, but not always, equal to a `min-content` minimum), and limit is the track sizing function passed as an argument to fit-content(). This is essentially calculated as the smaller of `minmax(auto, max-content)` and `minmax(auto, limit)`.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>grid containers</>}
  inherited="no"
  percentages={<>refer to corresponding dimension of the content area</>}
/>

## Formal syntax

```
grid-auto-columns =
  <track-size>+

<track-size> =
  <track-breadth>                                   |
  minmax( <inflexible-breadth> , <track-breadth> )  |
  fit-content( <length-percentage [0,∞]> )

<track-breadth> =
  <length-percentage [0,∞]>  |
  <flex [0,∞]>               |
  max-content                |
  auto

<inflexible-breadth> =
  <length-percentage [0,∞]>  |
  max-content                |
  auto

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines), `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-auto-columns`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-columns](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-columns)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-auto-flow.md
---

<APISummary />

## Introduction

The `grid-auto-flow` CSS property controls how the auto-placement algorithm works, specifying exactly how auto-placed items get flowed into the grid.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-auto-flow`
**Bundle:** `dist/grid-auto-flow.lynx.bundle`

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

const GridAutoFlow = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-auto-flow: row</text>
      <view className="container" style={{ gridAutoFlow: "row" }}>
        <text className="item" style={{ gridColumnStart: "span 2" }}>ONE</text>
        <text className="item" style={{ gridColumnStart: "span 2" }}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-auto-flow: column</text>
      <view className="container" style={{ gridAutoFlow: "column" }}>
        <text className="item" style={{ gridColumnStart: "span 2" }}>ONE</text>
        <text className="item" style={{ gridColumnStart: "span 2" }}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridAutoFlow />);

```



## Syntax

```css
grid-auto-flow: row;
grid-auto-flow: column;
grid-auto-flow: row dense;
grid-auto-flow: column dense;
grid-auto-flow: dense;
```

### Values

This property may take one of two forms:

a single keyword: one of row, column, or dense.

two keywords: row dense or column dense.

- `row`

  **Default value**. Items are placed by filling each row in turn, adding new rows as necessary. If neither row nor column is provided, row is assumed.

- `column`

  Items are placed by filling each column in turn, adding new columns as necessary.

- `dense`

  "dense" packing algorithm attempts to fill in holes earlier in the grid, if smaller items come up later. This may cause items to appear out-of-order, when doing so would fill in holes left by larger items.

  If it is omitted, a "sparse" algorithm is used, where the placement algorithm only ever moves "forward" in the grid when placing items, never backtracking to fill holes. This ensures that all of the auto-placed items appear "in order", even if this leaves holes that could have been filled by later items.

## Formal definition


<PropertyDefinition initialValue={<>row</>} appliesTo={<>grid containers</>} inherited="no" />

## Formal syntax

```
grid-auto-flow = [ row | column ] || dense
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-auto-flow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-flow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-flow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-auto-rows.md
---

<APISummary />

## Introduction

The `grid-auto-rows` CSS property specifies the size of an implicitly-created grid row track or pattern of tracks.

If a grid item is positioned into a row that is not explicitly sized by [grid-template-rows](/api/css/properties/grid-template-rows.md), implicit grid tracks are created to hold it. This can happen either by explicitly positioning into a row that is out of range, or by the auto-placement algorithm creating additional rows.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-auto-rows`
**Bundle:** `dist/grid-auto-rows.lynx.bundle`

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

const GridAutoRows = () => {
  const Container1Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoRows: "50px",
    gridTemplateColumns: "1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    height: "300px",
  };

  const Container2Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoRows: "1fr",
    gridTemplateColumns: "1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    height: "300px",
  };

  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-auto-rows: 50px</text>
      <view style={Container1Style}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-auto-rows: 1fr</text>
      <view style={Container2Style}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridAutoRows />);

```



## Syntax

```css
/* Keyword values */
grid-auto-rows: max-content;
grid-auto-rows: auto;

/* <length> values */
grid-auto-rows: 100px;

/* <percentage> values */
grid-auto-rows: 10%;
grid-auto-rows: 33.3%;

/* <flex> values */
grid-auto-rows: 0.5fr;
grid-auto-rows: 3fr;

/* minmax() values */
grid-auto-rows: minmax(100px, auto);
grid-auto-rows: minmax(max-content, 2fr);

/* multiple track-size values */
grid-auto-rows: 100px 150px 390px;
grid-auto-rows: 10% 33.3%;
grid-auto-rows: 0.5fr 3fr 1fr;
grid-auto-rows: 100px minmax(100px, auto) 10% 0.5fr fit-content(400px);
```

### Values

- `auto`

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `<length>`

  Is a non-negative length.

- `<percentage>`

  Is a non-negative `<percentage>` value relative to the block size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e. `minmax(auto, max-content)`), except that the track size is clamped at argument if it is greater than the `auto` minimum.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>grid containers</>}
  inherited="no"
  percentages={<>refer to corresponding dimension of the content area</>}
/>

## Formal syntax

```
/* Keyword values */
grid-auto-rows: max-content;
grid-auto-rows: auto;

/* <length> values */
grid-auto-rows: 100px;

/* <percentage> values */
grid-auto-rows: 10%;
grid-auto-rows: 33.3%;

/* <flex> values */
grid-auto-rows: 0.5fr;
grid-auto-rows: 3fr;

/* minmax() values */
grid-auto-rows: minmax(100px, auto);
grid-auto-rows: minmax(max-content, 2fr);

/* multiple track-size values */
grid-auto-rows: 100px 150px 390px;
grid-auto-rows: 10% 33.3%;
grid-auto-rows: 0.5fr 3fr 1fr;
grid-auto-rows: 100px minmax(100px, auto) 10% 0.5fr fit-content(400px);
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines) is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-auto-rows`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-rows](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-rows)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-column-end.md
---

<APISummary />

## Introduction

The `grid-column-end` CSS property specifies a grid item's end position within the grid column by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-column-end`
**Bundle:** `dist/grid-column-end.lynx.bundle`

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

const GridColumnEnd = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-column-end: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnEnd: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-end: 3</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnEnd: "3" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-end: -1</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnEnd: "-1" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridColumnEnd />);

```



## Syntax

```css
/* <number> values */
grid-column-end: 2;
grid-column-end: 3;

/* span <number> values*/
grid-column-end: span 1;
```

### Values

- `auto`

  **Default value**. Is a keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Contributes the nth grid line to the grid item's placement. If a negative integer is given, it instead counts in reverse, starting from the end edge of the explicit grid. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement such that the column end edge of the grid item's grid area is n lines from the start edge.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>grid items</>}
  inherited="no"
/>

## Formal syntax

```
grid-column-end = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-column-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-column-span.md
---

#<Deprecated />
 grid-column-span
<APISummary />

:::warning
This API is deprecated.
:::

## Introduction

Contributes a grid span to the grid item's placement.
If there are [`grid-column-start`](/api/css/properties/grid-column-start.md) and [`grid-column-end`](/api/css/properties/grid-column-end.md), this css property will be overridden.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-column-span`
**Bundle:** `dist/grid-column-span.lynx.bundle`

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

const GridColumnSpan = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-column-span: 1</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridColumnSpan in `@lynx-js/types`
            gridColumnSpan: "1",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-span: 2</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridColumnSpan in `@lynx-js/types`
            gridColumnSpan: "2",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-span: 3</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridColumnSpan in `@lynx-js/types`
            gridColumnSpan: "3",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridColumnSpan />);

```



## Syntax

```css
/* <number> values */
grid-column-span: 1;
grid-column-span: 2;
```

### Values

- `<number>`

  Contributes a grid span to the grid item's placement.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>1</code>
  </>
}
  appliesTo={<>grid items</>}
  inherited="no"
/>

## Formal syntax

```
grid-column-span = <number>
```

## Difference between web

- There is no such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-column-span`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-column-start.md
---

<APISummary />

## Introduction

The `grid-column-start` CSS property specifies a grid item's start position within the grid column by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-column-start`
**Bundle:** `dist/grid-column-start.lynx.bundle`

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

const GridColumnStart = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-column-start: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnStart: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-start: 2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnStart: "2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-start: -2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnStart: "-2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridColumnStart />);

```



## Syntax

```css
/* <number> values */
grid-column-start: 1;
grid-column-start: 2;

/* span  <number> values*/
grid-column-start: span 1;
```

### Values

- `auto`

  **Default value**. A keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Contributes the nth grid line to the grid item's placement. If a negative integer is given, it counts in reverse, starting from the end edge of the explicit grid. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement, such that the column start edge of the grid item's grid area is n lines from the end edge.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>grid items</>}
  inherited="no"
/>

## Formal syntax

```
grid-column-start = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-column-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-row-end.md
---

<APISummary />

## Introduction

The `grid-row-end` CSS property specifies a grid item's end position within the grid row by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-row-end`
**Bundle:** `dist/grid-row-end.lynx.bundle`

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

const GridRowEnd = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-row-end: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowEnd: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-end: span 2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowEnd: "span 2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-end: -1</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowEnd: "-1" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridRowEnd />);

```



## Syntax

```css
/* <number> values */
grid-row-end: 2;
grid-row-end: 3;

/* span  <number> values*/
grid-row-end: span 1;
```

### Values

- `auto`

  **Default value**. Is a keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Grid item's end position. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement such that the row end edge of the grid item's grid area is n lines from the start edge.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>grid items</>}
  inherited="no"
/>

## Formal syntax

```
grid-row-end = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-row-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-row-span.md
---

#<Deprecated />
 grid-row-span
<APISummary />

:::warning
This API is deprecated.
:::

## Introduction

Contributes a grid span to the grid item's placement.
If there are [`grid-row-start`](/api/css/properties/grid-row-start.md) and [`grid-row-end`](/api/css/properties/grid-row-end.md), this css property will be overridden.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-row-span`
**Bundle:** `dist/grid-row-span.lynx.bundle`

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

const GridRowSpan = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-row-span: 1</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridRowSpan in `@lynx-js/types`
            gridRowSpan: "1",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-span: 2</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridRowSpan in `@lynx-js/types`
            gridRowSpan: "2",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-span: 3</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridRowSpan in `@lynx-js/types`
            gridRowSpan: "3",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridRowSpan />);

```



## Syntax

```css
/* <number> values */
grid-row-span: 1;
grid-row-span: 2;
```

### Values

- `<number>`

  Contributes a grid span to the grid item's placement.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>1</code>
  </>
}
  appliesTo={<>grid items</>}
  inherited="no"
/>

## Formal syntax

```
grid-row-span = <number>
```

## Difference between web

- There is no such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-row-span`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-row-start.md
---

<APISummary />

## Introduction

The `grid-row-start` CSS property specifies a grid item's start position within the grid row by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-row-start`
**Bundle:** `dist/grid-row-start.lynx.bundle`

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

const GridRowStart = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-row-start: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowStart: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-start: 2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowStart: "2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-start: -2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowStart: "-2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridRowStart />);

```



## Syntax

```css
/* <number> values */
grid-row-start: 1;
grid-row-start: 2;

/* span  <number> values*/
grid-row-start: span 1;
```

### Values

- `auto`

  **Default value**. Is a keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Grid item's start position. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement; such that the row start edge of the grid item's grid area is n lines from the end edge.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>grid items</>}
  inherited="no"
/>

## Formal syntax

```
grid-row-start = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-row-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-template-columns.md
---

<APISummary />

## Introduction

The `grid-template-columns` CSS property defines track sizing functions of the grid columns.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-template-columns`
**Bundle:** `dist/grid-template-columns.lynx.bundle`

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

const GridTemplateColumn = () => {
  const titleStyle = {
    fontSize: "17px" as const,
    fontWeight: "600" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-template-columns: 100px 200px</text>
      <view className="container" style={{ gridTemplateColumns: "100px 200px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
      </view>

      <text style={titleStyle}>grid-template-columns: 1fr 100px</text>
      <view className="container" style={{ gridTemplateColumns: "1fr 100px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
      </view>

      <text style={titleStyle}>grid-template-columns: 1fr 2fr</text>
      <view className="container" style={{ gridTemplateColumns: "1fr 2fr" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
      </view>

      <text style={titleStyle}>grid-template-columns:</text>
      <text style={titleStyle}>20% max-content minmax(50px, max-content)</text>
      <view
        className="container"
        style={{
          gridTemplateColumns: "20% max-content minmax(50px, max-content)",
          gridTemplateRows: "auto",
          height: "max-content",
        }}
      >
        <text className="item">20%</text>
        <text className="item" style={{ fontSize: "35px" }}>No Wrap</text>
        <text className="item">min-width:50px, will fit the container</text>
      </view>
    </>
  );
};

root.render(<GridTemplateColumn />);

```



## Syntax

```css
/* Keyword value */
grid-template-columns: none;

/* <track-list> values */
grid-template-columns: 100px 1fr;
grid-template-columns: minmax(100px, 1fr);
grid-template-columns: fit-content(40%);
grid-template-columns: repeat(3, 200px);
```

### Values

- `<length>`

  [`<length>`](/api/css/data-type/length.md) is a non-negative length, giving the width of the column.

- `<percentage>`

  Is a non-negative [`<percentage>`](/api/css/data-type/percentage.md) value relative to the inline size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `auto`

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `max(minimum, min(limit, max-content))`, where minimum represents an `auto` minimum (which is often, but not always, equal to a `min-content` minimum), and limit is the track sizing function passed as an argument to fit-content(). This is essentially calculated as the smaller of `minmax(auto, max-content)` and `minmax(auto, limit)`.

- `repeat(<positive-integer>, [<length> | <percentage> | auto])`

  Represents a repeated fragment of the track list, allowing a large number of columns that exhibit a recurring pattern to be written in a more compact form.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    Indicates that there is no explicit grid. Any columns will be implicitly
    generated and their size will be determined by the
    <Link href="/api/css/properties/grid-auto-columns">
      <code>grid-auto-columns</code>
    </Link>
    property
  </>
}
  appliesTo={<>grid containers</>}
  inherited="no"
  percentages={<>refer to corresponding dimension of the content area</>}
/>

## Formal syntax

```
grid-template-columns =
  <track-list>

<track-list> =
   <track-size> | <track-repeat>

<track-size> =
  <track-breadth>                                   |
  minmax( <inflexible-breadth> , <track-breadth> )  |
  fit-content( <length-percentage [0,∞]> )

<track-repeat> =
  repeat([ <integer [1,∞]> ] , <track-size>)

<fixed-size> =
  <fixed-breadth>                                   |
  minmax( <fixed-breadth> , <track-breadth> )       |
  minmax( <inflexible-breadth> , <fixed-breadth> )

<fixed-repeat> =
  repeat( [ <integer [1,∞]> ] , <fixed-size>)

<track-breadth> =
  <length-percentage [0,∞]>  |
  <flex [0,∞]>               |
  max-content                |
  auto

<inflexible-breadth> =
  <length-percentage [0,∞]>  |
  max-content                |
  auto

<length-percentage> =
  <length>      |
  <percentage>

<fixed-breadth> =
  <length-percentage [0,∞]>
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines) is not supported.
- `none` is not supported.
- `masonry` and `subgrid` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-template-columns`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-columns](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-columns)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-template-rows.md
---

<APISummary />

## Introduction

The `grid-template-rows` CSS property defines track sizing functions of the grid rows.

## Examples

**This is an example below:  css-api**

**Entry:** `src/grid-template-rows`
**Bundle:** `dist/grid-template-rows.lynx.bundle`

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

const GridTemplateRow = () => {
  const titleStyle = {
    fontSize: "40rpx" as const,
    fontWeight: "700" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-template-rows: 40px 40px 40px;</text>
      <view className="container" style={{ gridTemplateRows: "40px 40px 40px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-template-rows: 1fr 60px 1fr;</text>
      <view className="container" style={{ gridTemplateRows: "1fr 60px 1fr" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-template-rows: 1fr max-content 2fr;</text>
      <view className="container" style={{ gridTemplateRows: "1fr max-content 2fr", height: "220px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">max-content: will take the maximum size of the items as the row size</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridTemplateRow />);

```



## Syntax

```css
/* auto values*/
grid-template-rows: auto auto;
/* <length> values */
grid-template-rows: 120px auto;
/* repeat func */
grid-template-rows: repeat(2, 100px) auto;
grid-template-rows: repeat(2, 100px auto) 200px;
```

### Values

- `<length>`

  [`<length>`](/api/css/data-type/length.md) is a non-negative length, giving the width of the row.

- `<percentage>`

  Is a non-negative [`<percentage>`](/api/css/data-type/percentage.md) value relative to the block size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `auto`

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e. `minmax(auto, max-content)`), except that the track size is clamped at argument if it is greater than the `auto` minimum.

- `repeat(<positive-integer>, [<length> | <percentage> | auto])`

  Represents a repeated fragment of the track list, allowing a large number of columns that exhibit a recurring pattern to be written in a more compact form.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    Is a keyword meaning that there is no explicit grid. Any rows will be
    implicitly generated and their size will be determined by the
    <Link href="/api/css/properties/grid-auto-rows">
      <code>grid-auto-rows</code>
    </Link>
    property
  </>
}
  appliesTo={<>grid containers</>}
  inherited="no"
  percentages={<>refer to corresponding dimension of the content area</>}
/>

## Formal syntax

```
grid-template-rows =
  <track-list>

<track-list> =
   <track-size> | <track-repeat>

<track-size> =
  <track-breadth>                                   |
  minmax( <inflexible-breadth> , <track-breadth> )  |
  fit-content( <length-percentage [0,∞]> )

<track-repeat> =
  repeat([ <integer [1,∞]> ] , <track-size>)

<fixed-size> =
  <fixed-breadth>                                   |
  minmax( <fixed-breadth> , <track-breadth> )       |
  minmax( <inflexible-breadth> , <fixed-breadth> )

<fixed-repeat> =
  repeat( [ <integer [1,∞]> ] , <fixed-size>)

<track-breadth> =
  <length-percentage [0,∞]>  |
  <flex [0,∞]>               |
  max-content                |
  auto

<inflexible-breadth> =
  <length-percentage [0,∞]>  |
  max-content                |
  auto

<length-percentage> =
  <length>      |
  <percentage>

<fixed-breadth> =
  <length-percentage [0,∞]>
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines) is not supported.
- `none` is not supported.
- `masonry` and `subgrid` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-template-rows`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-rows](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-rows)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/height.md
---

<APISummary />

## Introduction

The `height` CSS property specifies the height of an element. By default, the property defines the height of the border area. If [`box-sizing`](/api/css/properties/box-sizing.md) is set to `content-box`, however, it instead determines the height of the content area.

The [`min-height`](/api/css/properties/min-height.md) and [`max-height`](/api/css/properties/max-height.md) properties override `height`.

## Examples

**This is an example below:  css-api**

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

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

const Height = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view style={{ display: "linear", linearOrientation: "horizontal" }}>
        <text
          style={{
            height: "100px",
            border: "20px solid orange",
          }}
        >
          border-box
        </text>

        <text
          style={{
            height: "100px",
            border: "20px solid orange",
            boxSizing: "content-box",
          }}
        >
          content-box
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<Height />);

```



## Syntax

```css
/* <length> values */
height: 300px;
height: 25em;

/* <percentage> value */
height: 75%;

/* Keyword values */
height: max-content;
height: fit-content;
height: fit-content(20em);
height: auto;
```

### Values

- `auto`

  **Default value**. lynx will calculate and select a height for the specified element.

- `<length>`

  [`<length>`](/api/css/data-type/length.md) defines the height as a distance value.

- `<percentage>`

  Defines the height as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s height.

- `max-content`

  The intrinsic preferred height.

- `fit-content`

  [`fit-content`](/api/css/data-type/fit-content.md) uses the computed size with the available space replaced by the specified argument.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  animatable="yes"
  percentages={
  <>
    The percentage is calculated with respect to the height of the generated
    box's containing block
  </>
}
/>

## Formal syntax

```
height =
  auto                                      |
  <length-percentage [0,∞]>                 |
  max-content                               |
  fit-content( <length-percentage [0,∞]> )

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- By default, the property defines the height of the border area, while Web is `content area`.
- `min-content` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/image-rendering.md
---

<APISummary />

## Introduce

`image-rendering`

Used to set the image scaling algorithm. Currently only works with `<image>` and `background-image`
Currently it only applies to the element itself and will not take effect on child elements.

The image will be scaled when the dimensions specified by the front end are not the original dimensions of the image. For example, if there is an image with a physical pixel size of 100×100, but the actual width and height dimensions are set to 200×200px (or 50×50px), then the image will be reduced or reduced according to the algorithm specified by image-rendering. Enlarge to new size. This property has no effect on unscaled images.

## Examples

**This is an example below:  css-api**

**Entry:** `src/image-rendering`
**Bundle:** `dist/image-rendering.lynx.bundle`

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

const ImageRendering = () => {
  const url =
    "data:image/bmp;base64,Qk12BQAAAAAAADYAAAAoAAAAFQAAAOv///8BABgAAAAAAEAFAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA////AAAAAAAA////////AAAA////AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP///////////////////wAAAP///////wAAAP///////////////wAAAP///////////////////wAAAAAAAAD///8AAAAAAAAAAAD///8AAAD///8AAAAAAAAAAAD///////////8AAAD///8AAAAAAAAAAAD///8AAAAAAAAA////AAAAAAAAAAAA////AAAA////AAAAAAAA////////AAAA////AAAA////AAAAAAAAAAAA////AAAAAAAAAP///wAAAAAAAAAAAP///wAAAP///////wAAAAAAAP///////////wAAAP///wAAAAAAAAAAAP///wAAAAAAAAD///////////////////8AAAD///8AAAD///8AAAD///////////8AAAD///////////////////8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA////AAAA////AAAA////AAAA////AAAAAAAAAAAAAAAAAAAAAAAAAAAAAP///////////////////////////////wAAAP///wAAAP///////////////////////////////////////wAAAAAAAAD///8AAAD///////8AAAAAAAD///////8AAAAAAAAAAAAAAAAAAAAAAAD///8AAAAAAAD///8AAAAAAAAAAAAA////AAAAAAAA////////////////////AAAA////////AAAAAAAA////AAAAAAAA////AAAAAAAAAP///wAAAP///wAAAAAAAAAAAAAAAAAAAAAAAAAAAP///////////////////wAAAP///////////wAAAAAAAAD///////8AAAAAAAD///////////////////////////////8AAAD///////8AAAAAAAD///8AAAAAAAAAAAAA////AAAAAAAAAAAA////////AAAA////////AAAAAAAAAAAA////////////AAAA////////////AAAAAAAAAP///////////////////////////////////////wAAAAAAAAAAAAAAAAAAAAAAAP///wAAAAAAAP///////wAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8AAAD///8AAAD///////////8AAAAAAAAAAAD///////8AAAD///8AAAAA////////////////////AAAA////////AAAAAAAA////////AAAA////////////////////////AAAAAAAAAP///wAAAAAAAAAAAP///wAAAP///////////wAAAP///wAAAP///wAAAP///////wAAAAAAAAAAAP///wAAAAD///8AAAAAAAAAAAD///8AAAD///8AAAAAAAD///8AAAAAAAAAAAAAAAAAAAD///8AAAD///8AAAD///8AAAAA////AAAAAAAAAAAA////AAAA////////AAAA////////////////AAAAAAAAAAAA////AAAA////////AAAAAP///////////////////wAAAP///wAAAP///wAAAAAAAAAAAAAAAP///////wAAAAAAAP///////////wAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8AAAAAAAAAAAD///////////////////8AAAD///////8AAAD///8A";

  const verticalStyle = {
    linearOrientation: "vertical" as const,
  };

  const pixelatedStyle = {
    imageRendering: "pixelated" as const,
  };

  const autoStyle = {
    imageRendering: "auto" as const,
  };

  const crispEdgesStyle = {
    imageRendering: "crisp-edges" as const,
  };

  return (
    <scroll-view>
      <view style={verticalStyle}>
        <view className="image size" style={pixelatedStyle}></view>
        <view className="image size" style={autoStyle}></view>
        <view className="image size" style={crispEdgesStyle}></view>
      </view>

      <view style={verticalStyle}>
        <image src={url} className="size" style={pixelatedStyle}></image>
        <image src={url} className="size" style={autoStyle}></image>
        <image src={url} className="size" style={crispEdgesStyle}></image>
      </view>
    </scroll-view>
  );
};

root.render(<ImageRendering />);

```



## Syntax

```css
image-rendering: auto;
image-rendering: crisp-edges;
image-rendering: pixelated;
```

### Values

#### `auto`

Default value, platform layer default setting. Generally implemented as bilinear interpolation

#### `crisp-edges`

The image must be scaled using an algorithm that effectively preserves contrast and edges in the image, and that does not smooth the colors or introduce blur into the image during processing. This attribute value is suitable for pixel art works, such as images in some web games.
This is designed for pixel games (refer to Pixel-art scaling algorithms), and is not implemented by mainstream browsers.
Currently, lynx does not support it, and the effect is the same as auto.

#### `pixelated`

When zooming in and out of an image, the nearest neighbor algorithm is used, so the image appears to be made up of large blocks of pixels.

## Formal definition


<PropertyDefinition
  initialValue={<>auto</>}
  appliesTo={
  <>
    <code>image</code>, view's <code>background-image</code>
  </>
}
  inherited="no"
  animatable="no"
/>

## Formal syntax

```
image-rendering = auto | crisp-edges | pixelated
```

## The difference from the web

1. Only takes effect on the element itself, not on child elements.
2. Global attribute values ​​such as inherit, unset, etc. are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.image-rendering`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/image-rendering](https://developer.mozilla.org/zh-CN/docs/Web/CSS/image-rendering)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| iOS | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| HarmonyOS | 3.4 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay Android | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay iOS | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay macOS | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay Windows | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Web | ✅ Yes | it applies to an element itself, to any images set in its other properties, and to its descendants.; ⚠️ Partial implementation |

**Description:** The image-rendering CSS property sets an image scaling algorithm. The property applies to an element itself.




---
url: /api/css/properties/inset-inline-end.md
---

<APISummary />

## Introduction

The `inset-inline-end` CSS property defines the logical inline end inset of an element, which maps to a physical offset depending on the element's directionality. It corresponds to the [`right`](/api/css/properties/right.md) or [`left`](/api/css/properties/left.md) property depending on the values defined for [`direction`](/api/css/properties/direction.md).

In `LTR`, it corresponds to the [`right`](/api/css/properties/right.md) property.
In `RTL`, it corresponds to the [`left`](/api/css/properties/left.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/inset-inline-end`
**Bundle:** `dist/inset-inline-end.lynx.bundle`

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

const InsetInlineEnd = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    insetInlineStart: "20px",
    insetInlineEnd: "50px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <view className="intro" style={introStyle}></view>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<InsetInlineEnd />);

```



## Syntax

```css
/* <length> values */
inset-inline-end: 3px;
inset-inline-end: 2rpx;
inset-inline-end: 2.4em;
inset-inline-end: 3rem;

inset-inline-end: 10%;

/* Keyword value */
inset-inline-end: auto;

/* calc */
inset-inline-end: calc(1px + 1px);
```

### Values

The `inset-inline-end` property takes the same values as the [`left`](/api/css/properties/left.md) property.

## Formal definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>all elements</>} inherited="no" percentages={<>logical-width of containing block</>} />

## Formal syntax

```
inset-inline-end =
  auto                 |
  <length-percentage>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- In Lynx, `writing-mode` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.inset-inline-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |

**Description:** The inset-inline-end CSS property defines the logical inline end inset of an element, which maps to a physical offset depending on the element's directionality.




---
url: /api/css/properties/inset-inline-start.md
---

<APISummary />

## Introduction

The `inset-inline-start` CSS property defines the logical inline start inset of an element, which maps to a physical offset depstarting on the element's directionality. It corresponds to the [`right`](/api/css/properties/right.md) or [`left`](/api/css/properties/left.md) property depstarting on the values defined for [`direction`](/api/css/properties/direction.md).

In `LTR`, it corresponds to the [`left`](/api/css/properties/left.md) property.
In `RTL`, it corresponds to the [`right`](/api/css/properties/right.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/inset-inline-start`
**Bundle:** `dist/inset-inline-start.lynx.bundle`

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

const InsetInlineStart = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    insetInlineStart: "50px",
    insetInlineEnd: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <view className="intro" style={introStyle}></view>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<InsetInlineStart />);

```



## Syntax

```css
/* <length> values */
inset-inline-start: 3px;
inset-inline-start: 2rpx;
inset-inline-start: 2.4em;
inset-inline-start: 3rem;

inset-inline-start: 10%;

/* Keyword value */
inset-inline-start: auto;

/* calc */
inset-inline-start: calc(1px + 1px);
```

### Values

The `inset-inline-start` property takes the same values as the [`left`](/api/css/properties/left.md) property.

## Formal definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>all elements</>} inherited="no" percentages={<>logical-width of containing block</>} />

## Formal syntax

```
inset-inline-start =
  auto                 |
  <length-percentage>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- In Lynx, `writing-mode` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.inset-inline-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |

**Description:** The inset-inline-start CSS property defines the logical inline start inset of an element, which maps to a physical offset depending on the element's directionality.




---
url: /api/css/properties/justify-content.md
---

<APISummary />

## Introduction

The CSS `justify-content` property defines how distributes space between and around content items along the main-axis of a flexible box layout, [linear](/guide/ui/layout/linear-layout.md) container, and the inline axis of a grid layout container.

## Examples

**This is an example below:  css-api**

**Entry:** `src/justify-content`
**Bundle:** `dist/justify-content.lynx.bundle`

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

const JustifyContent = () => {
  const boxStyle = {
    width: "30px",
    height: "30px",
  };

  const redBoxStyle = {
    ...boxStyle,
    backgroundColor: "red",
  };

  const yellowBoxStyle = {
    ...boxStyle,
    backgroundColor: "yellow",
  };

  const greenBoxStyle = {
    ...boxStyle,
    backgroundColor: "green",
  };

  const blueBoxStyle = {
    ...boxStyle,
    backgroundColor: "blue",
  };

  const flexStartStyle = {
    justifyContent: "flex-start" as const,
  };

  const flexEndStyle = {
    justifyContent: "flex-end" as const,
  };

  const centerStyle = {
    justifyContent: "center" as const,
  };

  const spaceBetweenStyle = {
    justifyContent: "space-between" as const,
  };

  const spaceAroundStyle = {
    justifyContent: "space-around" as const,
  };

  const spaceEvenlyStyle = {
    justifyContent: "space-evenly" as const,
  };

  return (
    <>
      <text>justify-content:flex-start;</text>
      <view className="container" style={flexStartStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:flex-end;</text>
      <view className="container" style={flexEndStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:center;</text>
      <view className="container" style={centerStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:space-between;</text>
      <view className="container" style={spaceBetweenStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:space-around;</text>
      <view className="container" style={spaceAroundStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:space-evenly;</text>
      <view className="container" style={spaceEvenlyStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>
    </>
  );
};

root.render(<JustifyContent />);

```



## Syntax

```css
/* Positional alignment */
justify-content: center; /* Pack items around the center */
justify-content: start; /* Pack items from the start */
justify-content: end; /* Pack items from the end */
justify-content: flex-start; /* Pack flex items from the start */
justify-content: flex-end; /* Pack flex items from the end */

/* Distributed alignment */
justify-content: space-between; /* Distribute items evenly
                                   The first item is flush with the start,
                                   the last is flush with the end */
justify-content: space-around; /* Distribute items evenly
                                   Start and end gaps are half the size of the space
                                   between each item */
justify-content: space-evenly; /* Distribute items evenly
                                   Start, in-between, and end gaps have equal sizes */
justify-content: stretch; /* Distribute items evenly
                                   Stretch 'auto'-sized items to fit
                                   the container */
```

### Values

#### `stretch`

**Default value**.If the combined size of the items along the main axis is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container along the main axis.

:::info
For flex boxes, the `stretch` value behaves as `flex-start` or `start`. This is because, in flex boxes, stretching is controlled using the [`flex-grow`](/api/css/properties/flex-grow.md) property.

In [linear](/guide/ui/layout/linear-layout.md), the `stretch` value behaves as `flex-start` or `start`.
:::

#### `start`

The items are packed flush to each other toward the start edge of the alignment container in the main axis.

#### `end`

The items are packed flush to each other toward the end edge of the alignment container in the main axis.

#### `flex-start`

The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-start side. This only applies to flexible box layout items. For items that are not children of a flex container, this value is treated like `start`.

#### `flex-end`

The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-end side. This only applies to flexible box layout items. For items that are not children of a flex container, this value is treated like `end`.

#### `center`

The items are packed flush to each other toward the center of the alignment container along the main axis.

#### `space-between`

The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The first item is flush with the main-start edge, and the last item is flush with the main-end edge.

#### `space-around`

The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The empty space before the first and after the last item equals half of the space between each pair of adjacent items.

:::info
In [linear](/guide/ui/layout/linear-layout.md), the `space-around` value behaves as `flex-start` or `start`.
:::

#### `space-evenly`

The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

:::info
In [linear](/guide/ui/layout/linear-layout.md), the `space-evenly` value behaves as `flex-start` or `start`.
:::

## Formal definition


<PropertyDefinition initialValue={<>stretch</>} appliesTo={<>flex/grid/linear containers</>} inherited="no" />

## Formal syntax

```
justify-content = <content-distribution> | <content-position>

<content-distribution> =
  space-between  |
  space-around   |
  space-evenly   |
  stretch

<content-position> =
  center      |
  start       |
  end         |
  flex-start  |
  flex-end
```

## Difference with the web

- `normal` is not supported. Default value is `stretch`.
- `left` and `right` are not supported.
- `baseline`, `first baseline` and `last baseline` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.justify-content`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-content](https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/justify-items.md
---

<APISummary />

## Introduction

The CSS `justify-items` property defines the default [`justify-self`](/api/css/properties/justify-self.md) for all items of the box, giving them all a default way of justifying each box along the appropriate axis. It aligns the items inside their grid areas on the inline axis.

## Examples

**This is an example below:  css-api**

**Entry:** `src/justify-items`
**Bundle:** `dist/justify-items.lynx.bundle`

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

const JustifyItems = () => {
  const getGridStyle = (justifyItems: string) => ({
    display: "grid" as const,
    gridTemplateColumns: "auto",
    justifyItems: justifyItems,
  });

  return (
    <>
      <text>justify-items:stretch</text>
      <view style={getGridStyle("stretch")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
      <text>justify-items:start</text>
      <view style={getGridStyle("start")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
      <text>justify-items:end</text>
      <view style={getGridStyle("end")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
      <text>justify-items:center</text>
      <view style={getGridStyle("center")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
    </>
  );
};

root.render(<JustifyItems />);

```



## Syntax

```css
justify-items: stretch;
justify-items: center;
justify-items: start;
justify-items: end;
```

### Values

#### `stretch`

**Default value**. If the combined size of the items is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container.

#### `center`

The items are packed flush to each other toward the center of the alignment container.

#### `start`

The item is packed flush to each other toward the start edge of the alignment container in the appropriate axis.

#### `end`

The item is packed flush to each other toward the end edge of the alignment container in the appropriate axis.

## Formal definition


<PropertyDefinition initialValue={<>stretch</>} appliesTo={<>grid containers</>} inherited="no" />

## Formal syntax

```
justify-items = stretch | center | start | end
```

## Difference with the web

[mdn: justify-items](https://developer.mozilla.org/en/docs/Web/CSS/justify-items)

1. `normal` is not supported. Initial value is `stretch`.
2. `self-start`, `self-end`, `left`, `right`, `flex-start`, `flex-end` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.justify-items`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-items](https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-items)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |

**Description:** defines the default justify-self for all items of the box, giving them all a default way of justifying each box along the appropriate axis.




---
url: /api/css/properties/justify-self.md
---

<APISummary />

## Introduction

The CSS `justify-self` property sets the way a box is justified inside its alignment container along the appropriate axis. It aligns the items inside their grid areas on the inline axis.

## Examples

**This is an example below:  css-api**

**Entry:** `src/justify-self`
**Bundle:** `dist/justify-self.lynx.bundle`

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

const JustifySelf = () => {
  const containerStyle = {
    display: "grid" as const,
    gridTemplateColumns: "auto",
  };

  const getJustifySelfStyle = (justify: string) => ({
    justifySelf: justify,
  });

  return (
    <view style={containerStyle}>
      <text className="item" style={getJustifySelfStyle("stretch")}>justify-self:stretch</text>
      <text className="item" style={getJustifySelfStyle("center")}>justify-self:center</text>
      <text className="item" style={getJustifySelfStyle("start")}>justify-self:start</text>
      <text className="item" style={getJustifySelfStyle("end")}>justify-self:end</text>
    </view>
  );
};

root.render(<JustifySelf />);

```



## Syntax

```css
justify-self: auto;
justify-self: stretch;
justify-self: center;
justify-self: start;
justify-self: end;
```

### Values

#### `auto`

**Default value**. The value used is the value of the [`justify-items`](/api/css/properties/justify-items.md) property of the parents box.

#### `stretch`

If the combined size of the items is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container.

#### `center`

The items are packed flush to each other toward the center of the alignment container.

#### `start`

The item is packed flush to each other toward the start edge of the alignment container in the appropriate axis.

#### `end`

The item is packed flush to each other toward the end edge of the alignment container in the appropriate axis.

## Formal definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>grid items</>} inherited="no" />

## Formal syntax

justify-self =
auto |
stretch |
center |
start |
end

## Difference with the web

[mdn: justify-self](https://developer.mozilla.org/en/docs/Web/CSS/justify-self)

1. `normal` is not supported. Initial value is `stretch`.
2. `self-start`, `self-end`, `left`, `right`, `flex-start`, `flex-end` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.justify-self`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-self](https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-self)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |

**Description:** The CSS justify-self property sets the way a box is justified inside its alignment container along the appropriate axis.




---
url: /api/css/properties/left.md
---

<APISummary />

## Introduction

The `left` CSS property participates in specifying the horizontal position of a positioned element. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `left` depends on how the element is positioned (i.e., the value of the position property):

- When `position` is set to `absolute` or `fixed`, the `left` property specifies the distance between the element's outer margin of left edge and the inner border of left edge of its containing block. (The containing block is the ancestor to which the element is relatively positioned.)

- When `position` is set to `relative`, the `left` property specifies the distance the element's left edge is moved to the right from its normal position.

When both `left` and `right` are defined, and `width` constraints don't prevent it, the element will stretch to satisfy both. If the element cannot stretch to satisfy both, the `position` of the element is overspecified. When this is the case, the `left` value has precedence when the container is left-to-right; the `right` value has precedence when the container is right-to-left.

## Examples

**This is an example below:  css-api**

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

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

const Left = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view
        style={{
          width: "210px",
          height: "210px",
          border: "5px",
          borderColor: "black",
        }}
      >
        <view
          style={{
            position: "absolute",
            left: "80px",
            width: "50px",
            height: "50px",
            backgroundColor: "red",
          }}
        >
        </view>
        <view
          style={{
            position: "fixed",
            left: "155px",
            width: "50px",
            height: "50px",
            backgroundColor: "green",
          }}
        >
        </view>
        <view
          style={{
            position: "relative",
            left: "155px",
            width: "50px",
            height: "50px",
            backgroundColor: "yellow",
          }}
        >
        </view>
        <view
          style={{
            width: "50px",
            height: "50px",
            backgroundColor: "blue",
          }}
        >
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Left />);

```



## Syntax

```css
/* <length> values */
left: 3px;
left: 2rpx;
left: 2.4em;
left: 3rem;

left: 10%;

/* Keyword value */
left: auto;

/* calc */
left: calc(1px + 1px);
```

### Values

#### `auto`

**Default value**.

#### `<length>`

A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

- for absolutely positioned elements, the distance to the left edge of the containing block.

- for relatively positioned elements, the distance that the element is moved to the right of its normal position.

#### `<percentage>`

A `<percentage>` of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s width.

## Formal definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
left =
  auto                 |
  <length-percentage>  |

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** participates in setting the horizontal position of a positioned element. It has no effect on non-positioned elements.




---
url: /api/css/properties/letter-spacing.md
---

<APISummary />

## Introduction

The `letter-spacing` CSS property sets the horizontal spacing behavior between text characters.

## Examples

**This is an example below:  css-api**

**Entry:** `src/letter-spacing`
**Bundle:** `dist/letter-spacing.lynx.bundle`

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

const LetterSpacing = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const headerStyle = {
    backgroundColor: "#ccc",
    marginTop: "10px",
  };

  const text1Style = {
    fontSize: "16px",
    letterSpacing: "0px",
  };

  const text2Style = {
    fontSize: "16px",
    letterSpacing: "1px",
  };

  const text3Style = {
    fontSize: "16px",
    letterSpacing: "3rpx",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text style={headerStyle}>Letter Spacing Test</text>
          <text style={text1Style}>letter-spacing:0px</text>
          <text style={text2Style}>letter-spacing:1px</text>
          <text style={text3Style}>letter-spacing:3rpx</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<LetterSpacing />);

```



## Syntax

```css
/* <length> values */
letter-spacing: 0.3em;
letter-spacing: 3px;
letter-spacing: 0.3px;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Specifies extra inter-character space in addition to the default space between characters.

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal syntax

```
<length>
```

## Difference with Web

- Only support `<length>`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.letter-spacing`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/letter-spacing](https://developer.mozilla.org/zh-CN/docs/Web/CSS/letter-spacing)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/line-height.md
---

<APISummary />

## Introduction

The `line-height` CSS property sets the height of a line box. It's commonly used to set the distance between lines of text.

## Syntax

**This is an example below:  css-api**

**Entry:** `src/line-height`
**Bundle:** `dist/line-height.lynx.bundle`

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

const LineHeight = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const text1Style = {
    lineHeight: "30px",
  };

  const text2Style = {
    fontSize: "16px",
    lineHeight: "3",
  };

  const text3Style = {
    fontSize: "16px",
    lineHeight: "50px",
  };

  const inlineText1Style = {
    fontSize: "30px",
  };

  const inlineText2Style = {
    fontSize: "40px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text className="item" style={text1Style}>XX{"\n"}XX{"\n"}XX</text>
          <text className="item" style={text2Style}>XX{"\n"}XX{"\n"}XX</text>
          <text className="item" style={text3Style}>
            XX
            <text style={inlineText1Style}>XX</text>
            <text style={inlineText2Style}>XX</text>
          </text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<LineHeight />);

```



### Values

- normal <br />
  Default value.

- `<number>` <br />
  The used value is this unitless `<number>` multiplied by the element's own font size.

- `<length>` <br />
  The specified `<length>` is used in the calculation of the line box height.

## Formal definition


<PropertyDefinition initialValue={<>normal</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal syntax

```
normal | <length> | <number>
```

## Difference with web

- `line-height` only effect `<text>` element.

## Best Practices

- `line-height` in lynx will clip text content, so the value must be greater than element's font-size

- `line-height` is **paragraph style** . set in inline text has no effect.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.line-height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/line-height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/line-height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/linear-cross-gravity.md
---

#<Deprecated />
 linear-cross-gravity
<APISummary />

:::warning
This API is deprecated.
:::

## Introduction

Set the position of the child element on the cross axis of the parent container in [linear layout](/guide/ui/layout/linear-layout.md), is an style on the parent container. Similar to [`align-items`](/api/css/properties/align-items.md) in [flexible box layout](/guide/ui/layout/flexible-box-layout.md).

When using [`linear-layout-gravity`](/api/css/properties/linear-layout-gravity.md), [`align-self`](/api/css/properties/align-self.md), [`linear-cross-gravity`](/api/css/properties/linear-cross-gravity.md), and [`align-items`](/api/css/properties/align-items.md) simultaneously in a linear layout, the priority decreases from the first to the last. A higher-priority style will override a lower-priority style.

## Examples

**This is an example below:  css-api**

**Entry:** `src/linear-cross-gravity`
**Bundle:** `dist/linear-cross-gravity.lynx.bundle`

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

const LinearCrossGravity = () => {
  const [linearDirection, setLinearDirection] = useState(false);
  const container1Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "none" as const,
  };
  const container2Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "start" as const,
  };
  const container3Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "end" as const,
  };
  const container4Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "center" as const,
  };
  const container5Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "stretch" as const,
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const view1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
  };
  const view2Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "yellow" as const,
  };
  const view3Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "green" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearDirection(!linearDirection)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearDirection ? "row" : "column"}"</text>
      <text className="title">linear-cross-gravity:none;(default)</text>
      <view className="linear_container" style={container1Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:start;</text>
      <view className="linear_container" style={container2Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:end;</text>
      <view className="linear_container" style={container3Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:center;</text>
      <view className="linear_container" style={container4Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:stretch;</text>
      <view className="linear_container" style={container5Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearCrossGravity />);

```



## Syntax

```css
linear-cross-gravity: none;
linear-cross-gravity: start;
linear-cross-gravity: end;
linear-cross-gravity: center;
linear-cross-gravity: stretch;
```

### Values

- `none`

  **Default value**. When the size of the parent element cross axis size(such as the [`width`](/api/css/properties/width.md) when [`linear-direction: column`](/api/css/properties/linear-direction.md)) is fixed, and the size of the child element in this direction is auto, `none` will be equivalent to `stretch`. In other cases it is equivalent to `start`.

- `start`

  Align the beginning of the parent element's cross axis.

- `end`

  Align the end of the parent element's cross axis.

- `center`

  Align the center of the parent element's cross axis.

- `stretch`

  Fill the container's cross axis.

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>linear containers</>} inherited="no" />

## Formal syntax

```
linear-cross-gravity = none | start | end | center | stretch
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-cross-gravity`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.6 | - |
| Clay iOS | 1.6 | - |
| Clay macOS | 1.6 | - |
| Clay Windows | 1.6 | - |
| Web | ✅ Yes | - |

**Description:** Set the position of the child element on the cross axis of the parent container in linear layout.




---
url: /api/css/properties/linear-direction.md
---

<APISummary />

## Introduction

The `linear-direction` CSS property sets how linear items are placed in the linear container defining the main axis and the direction.

Note that the values `row`, `row-reverse` are affected by the directionality of the linear container. If its [`dir`](/api/css/properties/direction.md) attribute is `ltr`, `row` represents the horizontal axis oriented from the left to the right, and `row-reverse` from the right to the left; if the `dir` attribute is `rtl`, `row` represents the axis oriented from the right to the left, and `row-reverse` from the left to the right.

## Examples

**This is an example below:  css-api**

**Entry:** `src/linear-direction`
**Bundle:** `dist/linear-direction.lynx.bundle`

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

const LinearDirection = () => {
  const verticalContainerStyle = {
    display: "linear" as const,
    alignSelf: "center" as const,
    justifyContent: "center" as const,
    linearDirection: "column" as const,
  };

  const horizontalContainerStyle = {
    display: "linear" as const,
    alignSelf: "center" as const,
    justifyContent: "center" as const,
    linearDirection: "row" as const,
  };

  const redBoxStyle = {
    width: "70px",
    height: "70px",
    backgroundColor: "red",
  };

  const yellowBoxStyle = {
    width: "70px",
    height: "70px",
    backgroundColor: "yellow",
  };

  const greenBoxStyle = {
    width: "70px",
    height: "70px",
    backgroundColor: "green",
  };

  const textStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };

  return (
    <>
      <text style={textStyle}>linear-direction: column</text>
      <view style={verticalContainerStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
      </view>
      <view style={{ height: "50px" }} />
      <text style={textStyle}>linear-direction: row</text>
      <view style={horizontalContainerStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
      </view>
    </>
  );
};

root.render(<LinearDirection />);

```



## Syntax

```css
linear-direction: column;

/* Like <column>, but reversed */
linear-direction: column-reverse;

linear-direction: row;

/* Like <row>, but reversed */
linear-direction: row-reverse;
```

### Values

- `column`

  **Default value**. The linear container's main-axis is defined to be the same as vertical direction.

- `row`

  The linear container's main-axis is defined to be the same as the text direction. The main-start and main-end points are the same as the content direction.

- `column-reverse`

  Behaves the same as `column` but the main-start and main-end are opposite to the content direction.

- `row-reverse`

  Behaves the same as `row` but the main-start and main-end points are opposite to the content direction.

- `vertical` <Deprecated />

  Equivalent to `column`.

- `horizontal` <Deprecated />

  Equivalent to `row`.

- `horizontal-reverse` <Deprecated />

  Equivalent to `row-reverse`.

- `vertical-reverse` <Deprecated />

  Equivalent to `column-reverse`.

## Formal definition


<PropertyDefinition initialValue={<>column</>} appliesTo={<>linear containers</>} inherited="no" animatable="no" />

## Formal syntax

```
linear-direction = column | row | column-reverse | row-reverse
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-direction`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets how linear items are placed in the linear container defining the main axis and the direction.




---
url: /api/css/properties/linear-gravity.md
---

#<Deprecated />
 linear-gravity
<APISummary />

:::warning
This API is deprecated.
:::

## Introduction

The CSS `linear-gravity` property defines how distributes space between and around content items along the main-axis of a [linear](/guide/ui/layout/linear-layout.md) container. Similar to [flexible box layout](/guide/ui/layout/flexible-box-layout.md) [`justify-content`](/api/css/properties/justify-content.md).

:::info
When using `justify-content` and `linear-gravity` both, `linear-gravity` will override `justify-content`.
:::

## Examples

**This is an example below:  css-api**

**Entry:** `src/linear-gravity`
**Bundle:** `dist/linear-gravity.lynx.bundle`

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

const LinearGravity = () => {
  const [linearDirection, setLinearDirection] = useState(false);
  const container1Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "none" as const,
  };
  const container2Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "start" as const,
  };
  const container3Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "end" as const,
  };
  const container4Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "center" as const,
  };
  const container5Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "space-between" as const,
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const view1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
  };
  const view2Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "yellow" as const,
  };
  const view3Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "green" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearDirection(!linearDirection)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearDirection ? "row" : "column"}"</text>
      <text className="title">linear-gravity:none;(default)</text>
      <view className="linear_container" style={container1Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:start;</text>
      <view className="linear_container" style={container2Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:end;</text>
      <view className="linear_container" style={container3Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:center;</text>
      <view className="linear_container" style={container4Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:space-between;</text>
      <view className="linear_container" style={container5Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearGravity />);

```



## Syntax

```css
linear-gravity: none;
linear-gravity: start;
linear-gravity: end;
linear-gravity: center;
linear-gravity: space-between;
```

### Values

- `none`

  **Default value**. It is equivalent to `start`.

- `start`

  Align the beginning of the parent element main axis.

- `end`

  Align the end of the parent element main axis.

- `center`

  Align the center of the parent element's main axis.

- `space-between`

In the corresponding layout direction, the two ends are aligned and the middle interval is equal.

- `top` <Deprecated />

  Not recommended, it is recommended to use `start`. Align up, vertical layout takes effect.

- `bottom` <Deprecated />

  Not recommended, it is recommended to use `end`. Align down, vertical layout takes effect.

- `left` <Deprecated />

  Not recommended, it is recommended to use `start`. Align left, horizontal layout takes effect.

- `right` <Deprecated />

  Not recommended, it is recommended to use `end`. Align right, horizontal layout takes effect.

- `center-vertical` <Deprecated />

  Not recommended, it is recommended to use `center`. Centered vertically, vertical layout takes effect.

- `center-horizontal` <Deprecated />

  Not recommended, it is recommended to use `center`. Centered horizontally, horizontal layout takes effect.

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>linear containers</>} inherited="no" />

## Formal syntax

```
linear-gravity = none | start | end | center | space-between
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-gravity`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** defines how distributes space between and around content items along the main-axis of a linear container.




---
url: /api/css/properties/linear-layout-gravity.md
---

#<Deprecated />
 linear-layout-gravity
<APISummary />

:::warning
This API is deprecated.
:::

## Introduction

The position of the child element in the linear container, perpendicular to the layout direction, is a property of the child element's layout, similar to [`align-self`](/api/css/properties/align-self.md) in flexible box layout.

When using [`linear-layout-gravity`](/api/css/properties/linear-layout-gravity.md), [`align-self`](/api/css/properties/align-self.md), [`linear-cross-gravity`](/api/css/properties/linear-cross-gravity.md), and [`align-items`](/api/css/properties/align-items.md) simultaneously in a linear layout, the priority decreases from the first to the last. A higher-priority style will override a lower-priority style.

## Examples

**This is an example below:  css-api**

**Entry:** `src/linear-layout-gravity`
**Bundle:** `dist/linear-layout-gravity.lynx.bundle`

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

const LinearLayoutGravity = () => {
  const [linearOrientation, setLinearOrientation] = useState(false);
  const containerStyle = {
    linearOrientation: linearOrientation ? "horizontal" : "vertical" as "horizontal" | "vertical",
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const Container1View1Style = {
    width: "20px",
    height: "20px",
    linearLayoutGravity: "none" as const,
    backgroundColor: "red" as const,
  };
  const Container2View1Style = {
    width: "20px",
    height: "20px",
    linearLayoutGravity: "start" as const,
    backgroundColor: "red" as const,
  };
  const Container3View1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
    linearLayoutGravity: "end" as const,
  };
  const Container4View1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
    linearLayoutGravity: "center" as const,
  };
  const Container5View1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
    linearLayoutGravity: "stretch" as const,
  };
  const view2Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "yellow" as const,
  };
  const view3Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "green" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearOrientation(!linearOrientation)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearOrientation ? "row" : "column"}"</text>
      <text className="title">linear-layout-gravity:none;(default)</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container1View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:start;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container2View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:end;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container3View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:center;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container4View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:stretch;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container5View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearLayoutGravity />);

```



## Syntax

```css
linear-layout-gravity: none;
linear-layout-gravity: stretch;
linear-layout-gravity: start;
linear-layout-gravity: end;
linear-layout-gravity: center;
```

### Values

- `none`

  **Default value**。When the size of the parent element cross axis size(such as the [`width`](/api/css/properties/width.md) when [`linear-direction: column`](/api/css/properties/linear-direction.md)) is fixed, and the size of the child element in this direction is auto, `none` will be equivalent to `fill-horizontal` or `fill-vertical`. In other cases it is equivalent to `left` or `top`.

- `stretch`

  Fill the container's cross axis.

- `start`

  Align the beginning of the parent element's cross axis.

- `end`

  Align the end of the parent element's cross axis.

- `center`

  Align the center of the parent element's cross axis.

- `top` <Deprecated />

  Align the top of the parent element, the horizontal layout takes effect.

- `bottom` <Deprecated />

  Align the bottom of the parent element, the horizontal layout takes effect.

- `left` <Deprecated />

  Align the left side of the parent element, vertical layout takes effect.

- `right` <Deprecated />

  Align the right side of the parent element, vertical layout takes effect.

- `center-vertical` <Deprecated />

  Centered in the vertical direction, the horizontal layout of the parent element takes effect.

- `center-horizontal` <Deprecated />

  Centered in the horizontal direction, the vertical layout of the parent element takes effect.

- `fill-vertical` <Deprecated />

  Fill the entire container vertically, and the horizontal layout of the parent element takes effect.

- `fill-horizontal` <Deprecated />

  Fill up the container horizontally, and the vertical layout of the parent element takes effect.

## Formal definition


<PropertyDefinition initialValue={<>none</>} appliesTo={<>linear items</>} inherited="no" />

## Formal syntax

```
linear-layout-gravity = none | stretch | start | end | center
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-layout-gravity`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** The position of the child element in the linear container, perpendicular to the layout direction.


## FAQ

- `None` and `top`/`left` in `linear-layout-gravity` are not the same. The specific differences are as follows:

- When the parent's non-layout orientation is fixed size, none behaves the same as `fill-vertical`/`fill-horizontal`, i.e., fills the parent's non-layout orientation.
  `None` behaves the same as `top`/`right` when the parent's non-layout orientation is not a fixed size.



---
url: /api/css/properties/linear-weight-sum.md
---

#<Deprecated />
 linear-weight-sum
<APISummary />

:::warning
This API is deprecated.
:::

## Introduction

Child element's weight sum in [linear](/guide/ui/layout/linear-layout.md).

When `linear-weight-sum` property of the [linear](/guide/ui/layout/linear-layout.md) view is non-zero.

- The linear-layout first lays out all the child elements whose [`linear-weight:0`](/api/css/properties/linear-weight.md), and calculates the width of these child elements in the layout direction.
- The remaining `linear-weight` non-zero child elements will be allocated the remaining width(linear layout view width minus the width of all `linear-weight:0` child elements) in the main axis according to their `linear-weight`. For ease of presentation, we view "the sum of the children `linear-weight` " as symbol "S".

  - When `linear-weight-sum` \<= S:

    main size of child = corresponding linear-weight ÷ S ✖️ remaining main size width

  - When `linear-weight-sum` > S:

    main size of child = corresponding linear-weight ÷ linear-weight-sum ✖️ remaining main size width

:::tip
1.linear container's main axis size need set a fixed value;

2.It is not supported to use a fixed value and weight at the same time. If there is a `linear-weight`, the fixed value is automatically ignored (performance first);
:::

## Examples

In the figure, the width of the parent element is 400px, the first element is fixed at 100px, and the remaining width is 300px. The second and third elements specify the size, and are allocated according to the weight. The second element is 200px wide and the third element is 100px wide.

**This is an example below:  css-api**

**Entry:** `src/linear-weight-sum`
**Bundle:** `dist/linear-weight-sum.lynx.bundle`

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

const LinearWeightSum = () => {
  const containerStyle = {
    display: "linear" as const,
    linearDirection: "column" as const,
    height: "400px",
    linearWeightSum: "3",
    marginTop: "30px",
  };

  const textStyle = {
    fontSize: "40rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const text2Style = {
    fontSize: "40rpx" as const,
    fontWeight: "800" as const,
  };

  const redBoxStyle = {
    width: "100%",
    alignItems: "center" as const,
    justifyContent: "center" as const,
    backgroundColor: "red",
    height: "100px",
  };

  const yellowBoxStyle = {
    width: "100%",
    alignItems: "center" as const,
    justifyContent: "center" as const,
    backgroundColor: "yellow",
    linearWeight: 2,
  };

  const greenBoxStyle = {
    width: "100%",
    alignItems: "center" as const,
    justifyContent: "center" as const,
    backgroundColor: "green",
    linearWeight: 1,
  };

  return (
    <>
      <text style={textStyle}>linear-weight-sum: 3</text>
      <text style={textStyle}>height: 400px</text>
      <view style={containerStyle}>
        <view style={redBoxStyle}>
          <text style={text2Style}>height: 100px</text>
        </view>
        <view style={yellowBoxStyle}>
          <text style={text2Style}>linear-weight: 2</text>
        </view>
        <view style={greenBoxStyle}>
          <text style={text2Style}>linear-weight: 1</text>
        </view>
      </view>
    </>
  );
};

root.render(<LinearWeightSum />);

```



## Syntax

```css
linear-weight-sum: 2;
linear-weight-sum: 5.5;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid. **Default value is 0**.

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>linear containers</>} inherited="no" />

## Formal syntax

```
linear-weight-sum = <number>
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-weight-sum`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | Do not support this property on the inline style; ⚠️ Partial implementation |

**Description:** Child element's weight sum in linear layout.


## FAQ

- linear container's main axis size need set a fixed value;

- It is not supported to use a fixed value and weight at the same time. If there is a linear-weight, the fixed value is automatically ignored (performance first);



---
url: /api/css/properties/linear-weight.md
---

<APISummary />

## Introduction

Child element's weight in [linear](/guide/ui/layout/linear-layout.md).
The parent container automatically allocates the length of the corresponding side of the child elements according to the weight value ratio of all child elements and the size of the remaining space.

## Examples

**This is an example below:  css-api**

**Entry:** `src/linear-weight`
**Bundle:** `dist/linear-weight.lynx.bundle`

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

const LinearWeight = () => {
  const [linearOrientation, setLinearOrientation] = useState(false);
  const containerStyle = {
    linearOrientation: linearOrientation ? "horizontal" : "vertical" as "horizontal" | "vertical",
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const Container1View1Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "red" as const,
  };
  const Container1View2Style = {
    width: "30px",
    height: "30px",
    linearWeight: 2,
    backgroundColor: "yellow" as const,
  };
  const Container1View3Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "blue" as const,
  };

  const Container2View1Style = {
    width: "30px",
    height: "30px",
    linearWeight: 1,
    backgroundColor: "red" as const,
  };
  const Container2View2Style = {
    width: "30px",
    height: "30px",
    linearWeight: 1,
    backgroundColor: "yellow" as const,
  };
  const Container2View3Style = {
    width: "30px",
    height: "30px",
    linearWeight: 1,
    backgroundColor: "blue" as const,
  };

  const Container3View1Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "red" as const,
  };
  const Container3View2Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "yellow" as const,
  };
  const Container3View3Style = {
    width: "30px",
    height: "30px",
    linearWeight: 2,
    backgroundColor: "blue" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearOrientation(!linearOrientation)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearOrientation ? "row" : "column"}"</text>
      <text className="title">linear-weight: 0.5 2 0.5</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container1View1Style} />
        <view style={Container1View2Style} />
        <view style={Container1View3Style} />
      </view>

      <text className="title">linear-weight: 1 1 1</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container2View1Style} />
        <view style={Container2View2Style} />
        <view style={Container2View3Style} />
      </view>

      <text className="title">linear-weight: 0.5 0.5 2</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container3View1Style} />
        <view style={Container3View2Style} />
        <view style={Container3View3Style} />
      </view>
    </scroll-view>
  );
};

root.render(<LinearWeight />);

```



## Syntax

```css
linear-weight: 3;
linear-weight: 5;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid. **Default value is 0**. When the linear-weight of a sub-element in linear layout is 0, the layout of the child element will not be affected by the linear-weight.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>0</code>
  </>
}
  appliesTo={<>linear items</>}
  inherited="no"
/>

## Formal syntax

```
linear-weight = <number>
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-weight`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** Child element's weight in linear layout.


## FAQ

- It is not supported to use a fixed value and weight at the same time. If there is a `weight`, the fixed value is automatically ignored (performance first).



---
url: /api/css/properties/margin-bottom.md
---

<APISummary />

## Introduction

The `margin-bottom` CSS property sets the margin area on the bottom of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below:  css-api**

**Entry:** `src/margin-bottom`
**Bundle:** `dist/margin-bottom.lynx.bundle`

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

const MarginBottom = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginTop: "10px",
            marginBottom: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginBottom />);

```



## Syntax

```css
/* <length> values */
margin-bottom: 0.5em;
margin-bottom: 0;
margin-bottom: 2rpx;

/* <percentage> value */
margin-bottom: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal Definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
margin-bottom =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-bottom](https://developer.mozilla.org/en/docs/Web/CSS/margin-bottom)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | ✅ Yes | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-inline-end.md
---

<APISummary />

## Introduction

The `margin-inline-end` CSS property defines the logical inline end margin of an element.

In `LTR` direction, it corresponds to the [`margin-right`](/api/css/properties/margin-right.md) property.
In `RTL` direction, it corresponds to the [`margin-left`](/api/css/properties/margin-left.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/margin-inline-end`
**Bundle:** `dist/margin-inline-end.lynx.bundle`

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

const MarginInlineEnd = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    marginInlineStart: "10px",
    marginInlineEnd: "50px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={introStyle}>1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<MarginInlineEnd />);

```



## Syntax

```css
/* <length> values */
margin-inline-end: 0.5em;
margin-inline-end: 0px;
margin-inline-end: 2rpx;

/* <percentage> value */
margin-inline-end: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value, can be positive, zero, or negative.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block). It can be positive, zero, or negative.

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
margin-inline-end =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-inline-end](https://developer.mozilla.org/en/docs/Web/CSS/margin-inline-end)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
3. Lynx does not support writing mode.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-inline-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-inline-start.md
---

<APISummary />

## Introduction

The `margin-inline-start` CSS property defines the logical inline start margin of an element.

In `LTR` direction, it corresponds to the [`margin-left`](/api/css/properties/margin-left.md) property.
In `RTL` direction, it corresponds to the [`margin-right`](/api/css/properties/margin-right.md) property.

## Examples

**This is an example below:  css-api**

**Entry:** `src/margin-inline-start`
**Bundle:** `dist/margin-inline-start.lynx.bundle`

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

const MarginInlineStart = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    marginInlineStart: "50px",
    marginInlineEnd: "10px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={introStyle}>1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<MarginInlineStart />);

```



## Syntax

```css
/* <length> values */
margin-inline-start: 0.5em;
margin-inline-start: 0px;
margin-inline-start: 2rpx;

/* <percentage> value */
margin-inline-start: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value, can be positive, zero, or negative.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
margin-inline-start =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-inline-start](https://developer.mozilla.org/en/docs/Web/CSS/margin-inline-start)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
3. Lynx does not support writing mode.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-inline-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-left.md
---

<APISummary />

## Introduction

The `margin-left` CSS property sets the margin area on the left of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below:  css-api**

**Entry:** `src/margin-left`
**Bundle:** `dist/margin-left.lynx.bundle`

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

const MarginLeft = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginLeft: "10px",
            marginRight: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginLeft />);

```



## Syntax

```css
/* <length> values */
margin-left: 0.5em;
margin-left: 0;
margin-left: 2rpx;

/* <percentage> value */
margin-left: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
margin-left =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-left](https://developer.mozilla.org/en/docs/Web/CSS/margin-left)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-right.md
---

<APISummary />

## Introduction

The `margin-right` CSS property sets the margin area on the right of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below:  css-api**

**Entry:** `src/margin-right`
**Bundle:** `dist/margin-right.lynx.bundle`

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

const MarginRight = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginLeft: "10px",
            marginRight: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginRight />);

```



## Syntax

```css
/* <length> values */
margin-right: 0.5em;
margin-right: 0;
margin-right: 2rpx;

/* <percentage> value */
margin-right: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
margin-right =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-right](https://developer.mozilla.org/en/docs/Web/CSS/margin-right)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-top.md
---

<APISummary />

## Introduction

The `margin-top` CSS property sets the margin area on the top of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below:  css-api**

**Entry:** `src/margin-top`
**Bundle:** `dist/margin-top.lynx.bundle`

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

const MarginTop = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginTop: "10px",
            marginBottom: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginTop />);

```



## Syntax

```css
/* <length> values */
margin-top: 0.5em;
margin-top: 0;
margin-top: 2rpx;

/* <percentage> value */
margin-top: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
margin-top =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-top](https://developer.mozilla.org/en/docs/Web/CSS/margin-top)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin.md
---

<APISummary />

## Introduction

The margin CSS shorthand property sets the margin area on all four sides of an element.

This property is a shorthand for the following CSS properties: [margin-top](/api/css/properties/margin-top.md), [margin-right](/api/css/properties/margin-right.md), [margin-bottom](/api/css/properties/margin-bottom.md), [margin-left](/api/css/properties/margin-left.md).

## Examples

**This is an example below:  css-api**

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

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

const Margin = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text className="intro" style={{ margin: "20px" }}>
          margin: 20px; All sides
        </text>
      </view>

      <view className="con">
        <text className="intro" style={{ margin: "20px 5px" }}>
          margin: 20px 5px; Top/Bottom | Left/Right
        </text>
      </view>

      <view className="con">
        <text className="intro" style={{ margin: "20px 15px 10px" }}>
          margin: 20px 15px 10px; Top | Left/Right | Bottom
        </text>
      </view>

      <view className="con">
        <text className="intro" style={{ margin: "20px 15px 10px 5px" }}>
          margin: 20px 15px 10px 5px; Top | Right | Bottom | Left
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<Margin />);

```



## Syntax

```css
/* Apply to all four sides */
margin: 1em;
margin: -3px;

/* top and bottom | left and right */
margin: 5% auto;

/* top | left and right | bottom */
margin: 1em auto 2em;

/* top | right | bottom | left */
margin: 2px 1em 0 auto;
```

The margin property may be specified using one, two, three, or four values. Each value is a [`<length>`](/api/css/data-type/length.md), a [`<percentage>`](/api/css/data-type/percentage.md), or the keyword `auto`. Negative values draw the element closer to its neighbors than it would be by default.

- When one value is specified, it applies the same margin to all four sides.

- When two values are specified, the first margin applies to the top and bottom, the second to the left and right.

- When three values are specified, the first margin applies to the top, the second to the right and left, the third to the bottom.

- When four values are specified, the margins apply to the top, right, bottom, and left in that order (clockwise).

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    as each of the properties of the shorthand: <br />
    <ul style={{ listStyleType: 'disc', paddingLeft: '1.5rem' }}>
      <li> margin-bottom: 0</li>
      <li>margin-left: 0</li>
      <li>margin-right: 0</li>
      <li>margin-top: 0</li>
    </ul>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  percentages={<>refer to the width of the containing block</>}
/>

## Formal syntax

```
margin =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin](https://developer.mozilla.org/en/docs/Web/CSS/margin)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/mask-image.md
---

<APISummary />

## Introduction

The <code>mask-image</code>
 CSS property sets the image that is used as mask layer for an element.
By default this means the alpha channel of the mask image will be multiplied with the alpha channel of the element.
## Syntax

```css
/* Keyword value */
mask-image: none;

/* <image> values */
mask-image: linear-gradient(rgba(0, 0, 0, 1), transparent);
mask-image: url(mask.png);

/* Multiple values */
mask-image: url(mask.png), linear-gradient(rgba(0, 0, 0, 1), transparent);
```

### Values

#### `none`

This keyword is interpreted as an opaque white image layer.

#### `<image>`

An image value used as mask image layer.

### Formal Definition


<PropertyDefinition
  initialValue={<>none</>}
  appliesTo={
  <>
    <code>view</code> only
  </>
}
  inherited="no"
/>

## Formal Syntax

```
mask-image =
  <mask-reference>#

<mask-reference> =
  none       |
  <image>

<image> =
  <url()>    |
  <gradient>

<url()> =
  url( <string> )
```

## Difference with the Web

1. SVG element is not supported. Only bitmap url or gradient is supported.
2. image() function is not supported.
3. `<url()>` supports `url()` function only.
4. global value are not supported (e.g. inherit, unset, init and etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.mask-image`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask-image](https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask-image)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | src(), image() functions and svg elements reference are not supported; ⚠️ Partial implementation |
| iOS | 2.13 | src(), image() functions and svg elements reference are not supported; ⚠️ Partial implementation |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** The mask-image CSS property sets the image that is used as mask layer for an element. By default this means the alpha channel of the mask image will be multiplied with the alpha channel of the element. This can be controlled with the mask-mode property.




---
url: /api/css/properties/mask.md
---

<APISummary />

## Introduction

The `mask` CSS shorthand property hides an element (partially or fully) by masking or clipping the image at specific points.

## Constituent properties

This property is a shorthand for the following CSS properties:

- mask-clip
- mask-image
- mask-origin
- mask-position
- mask-repeat
- mask-size

## Syntax

```css
/* Keyword values */
mask: none;

/* Image values */
mask: url(mask.png); /* Pixel image used as mask */

/* Combined values */
mask: url(mask.png) 40px 20px; /* Pixel image used as mask positioned 40px from the top and 20px from the left */
mask: url(mask.png) 0 0/50px 50px; /* Pixel image used as mask with a width and height of 50px */
mask: url(mask.png) repeat-x; /* Pixel image used as horizontally repeated mask */
mask: url(mask.png) stroke-box; /* Pixel image used as mask extending to the box enclosed by the stroke */

/* Multiple masks */
mask:
  url(masks.png) left / 16px repeat-y,
  /* Pixel image is used as a mask on the left-hand side with a width of 16px */
    url(masks.png) right / 16px repeat-y; /* Pixel image is used as a mask on the right-hand side with a width of 16px */
```

### Values

#### `<mask-reference>`

Sets the mask image source. See [mask-image](/api/css/properties/mask-image.md).

#### `<position>`

Sets the position of the mask image. See [mask-position](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-position).

#### `<bg-size>`

Sets the size of the mask image. See [mask-size](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-size).

#### `<repeat-style>`

Sets the repetition of the mask image. See [mask-repeat](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-repeat).

#### `<geometry-box>`

If only one `<geometry-box` value is given, it sets both [mask-origin](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-origin) and [mask-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-clip). If two `<geometry-box>` values are present, then the first sets mask-origin and the second sets [mask-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-clip).

#### `<geometry-box> | no-clip`

Sets the area that is affected by the mask image. See [mask-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-clip).

## Formal definition

|                              |                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Initial values**           | as each of the properties of the shorthand: <br /> <ul style={{ listStyleType: "disc", paddingLeft: "1.5rem" }}> <li> [mask-image](/api/css/properties/mask-image.md): none</li> <li>mask-repeat: repeat</li><li>mask-position: center</li><li>mask-clip: border-box</li><li>mask-origin: border-box</li><li>mask-size: auto</li></ul> |
| **Applies to**               | Views only. It may work on some other elements, but it is recommended that only use it on <code>\<view></code>                                                                                                                                                                                                                         |
| **Inherited**                | No                                                                                                                                                                                                                                                                                                                                     |
| **Percentages**              | as each of the properties of the shorthand: <br /> <ul style={{ listStyleType:"disc", paddingLeft: "1.5rem"}}><li> mask-position: refer to size of mask painting area minus size of mask layer image (see the text for background-position)</li></ul>                                                                                  |
| **Creates stacking context** | yes                                                                                                                                                                                                                                                                                                                                    |

## Formal Syntax

```
mask =
  <mask-layer>#

<mask-layer> =
  <mask-reference>               ||
  <position> [ / <bg-size> ]?    ||
  <repeat-style>                 ||
  <box>                          ||
  <compositing-operator>         ||
  <masking-mode>

<mask-reference> =
  none       |
  <image>

<image> =
  <url()>   |
  <gradient>

<url()> =
  url( <string> )

<position> =
  [ left | center | right ] && [ top | center | bottom ]            |
  [ left | center | right | <length-percentage> ]
    [ top | center | bottom | <length-percentage> ]?                |
  [ [ left | right ] <length-percentage> ] &&
    [ [ top | bottom ] <length-percentage> ]

<bg-size> =
  [ <length-percentage> | auto ]{1,2}  |
  cover                                |
  contain

<repeat-style> =
  repeat-x                             |
  repeat-y                             |
  [ repeat | space | round | no-repeat ]{1,2}

<box> =
  border-box     |
  padding-box    |
  content-box

<compositing-operator> =
  add        |
  subtract   |
  intersect  |
  exclude

<masking-mode> =
  alpha         |
  luminance     |
  match-source

<length-percentage> =
  <length>      |
  <percentage>

```

## Difference with the Web

1. `mask-type` not supported in Lynx.
2. `mask-image` not support [SVG]() reference.
3. only support border-box, padding-box and content-box.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.mask`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask](https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | mask-type, mask-composite are not supported; ⚠️ Partial implementation |
| iOS | 2.13 | mask-type, mask-composite are not supported; ⚠️ Partial implementation |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.4 | - |
| Clay iOS | 3.4 | - |
| Clay macOS | 3.4 | - |
| Clay Windows | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** The mask CSS shorthand property hides an element (partially or fully) by masking or clipping the image at specific points.




---
url: /api/css/properties/max-height.md
---

<APISummary />

## Introduction

To specify max height of a view. It prevents the applied value of [`height`](/api/css/properties/height.md) becoming larger than the specified value of `max-height`.
The priority of `max-height` is higher than [`height`](/api/css/properties/height.md) and [`min-height`](/api/css/properties/min-height.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/max-height`
**Bundle:** `dist/max-height.lynx.bundle`

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

const MaxHeight = () => {
  const containerStyle = {
    display: "linear" as const,
    linearDirection: "row" as const,
  };

  const firstBoxStyle = {
    height: "300px",
    backgroundColor: "green",
    width: "100px",
  };

  const secondBoxStyle = {
    height: "400px",
    backgroundColor: "yellow",
    width: "100px",
    maxHeight: "300px",
  };

  const thirdBoxStyle = {
    height: "300px",
    backgroundColor: "blue",
    width: "100px",
    minHeight: "400px",
    maxHeight: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>height: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>height: 400px; max-height: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>height: 300px; min-height: 400px; max-height: 200px</text>
      </view>
    </view>
  );
};

root.render(<MaxHeight />);

```



## Syntax

```css
/* <length> */
max-height: 120px;
max-height: 10em;

/* <percentage> */
max-height: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) Defines the max-height as an absolute value.

#### `<percentage>`

Defines the `max-height` as a percentage of the containing block's height.

## Formal definition


<PropertyDefinition
  initialValue={<>no limit</>}
  appliesTo={<>all elements</>}
  inherited="no"
  percentages={
  <>
    The percentage is calculated with respect to the height of the generated
    box's containing block
  </>
}
/>

## Formal syntax

```css
/* <length> */
max-height: 120px;
max-height: 10em;

/* <percentage> */
max-height: 75%;
```

## Difference with the Web

[mdn:max-height](https://developer.mozilla.org/en-US/docs/Web/CSS/max-height)

1. In Lynx, the priority of `max-height` is higher than `height` and `min-height`. While in Web, `max-height` overrides `height`, but `min-height` overrides `max-height`.
2. In Lynx, if `max-height` is specified smaller than `min-height`, `min-height` will be ignored.
3. `none`, `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.max-height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the maximum height of an element.




---
url: /api/css/properties/max-width.md
---

<APISummary />

## Introduction

To specify max width of a view. It prevents the applied value of [`width`](/api/css/properties/width.md) becoming larger than the specified value of `max-width`.
The priority of `max-width` is higher than [`width`](/api/css/properties/width.md) and [`min-width`](/api/css/properties/min-width.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/max-width`
**Bundle:** `dist/max-width.lynx.bundle`

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

const MaxWidth = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const firstBoxStyle = {
    width: "300px",
    backgroundColor: "green",
  };

  const secondBoxStyle = {
    width: "300px",
    backgroundColor: "yellow",
    maxWidth: "300px",
  };

  const thirdBoxStyle = {
    width: "300px",
    backgroundColor: "blue",
    minWidth: "400px",
    maxWidth: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>width: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>width: 400px; max-width: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>width: 300px; min-width: 400px; max-width: 200px</text>
      </view>
    </view>
  );
};

root.render(<MaxWidth />);

```



## Syntax

```css
/* <length> */
max-width: 120px;
max-width: 10em;

/* <percentage> */
max-width: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) defines the max-width as an absolute value.

#### `<percentage>`

Defines the max-width as a percentage of the containing block's width.

## Formal definition


<PropertyDefinition initialValue={<>no limit</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} animatable="yes" />

## Formal syntax

```
max-width = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn:max-width](https://developer.mozilla.org/en-US/docs/Web/CSS/max-width)

1. In Lynx, the priority of `max-width` is higher than `width` and `min-width`. While in Web, `max-width` overrides `width`, but `min-width` overrides `max-width`.
2. In Lynx, if `max-width` is specified smaller than `min-width`, `min-width` will be ignored.
3. `none`, `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.max-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the maximum width of an element.




---
url: /api/css/properties/min-height.md
---

<APISummary />

## Introduction

To specify min height of a view. It prevents the applied value of [`height`](/api/css/properties/height.md) becoming larger than the specified value of `min-height`.
The priority of `min-height` is higher than [`height`](/api/css/properties/height.md) but lower than [`max-height`](/api/css/properties/max-height.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/min-height`
**Bundle:** `dist/min-height.lynx.bundle`

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

const MinHeight = () => {
  const containerStyle = {
    display: "linear" as const,
    linearDirection: "row" as const,
  };

  const firstBoxStyle = {
    height: "300px",
    backgroundColor: "green",
    width: "100px",
  };

  const secondBoxStyle = {
    height: "0px",
    backgroundColor: "yellow",
    width: "100px",
    minHeight: "300px",
  };

  const thirdBoxStyle = {
    height: "0px",
    backgroundColor: "blue",
    width: "100px",
    minHeight: "300px",
    maxHeight: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>height: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>height: 0px; min-height: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>height: 0px; min-height: 300px; max-height: 200px</text>
      </view>
    </view>
  );
};

root.render(<MinHeight />);

```



## Syntax

```css
/* <length> */
min-height: 120px;
min-height: 10em;

/* <percentage> */
min-height: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) defines the min-height as an absolute value. Default to `0px`.

#### `<percentage>`

Defines the `min-height` as a percentage of the containing block's height.

## Formal definition


<PropertyDefinition
  initialValue={<>0px</>}
  appliesTo={<>all elements</>}
  inherited="no"
  percentages={
  <>
    The percentage is calculated with respect to the height of the generated
    box's containing block
  </>
}
  animatable="yes"
/>

## Formal syntax

```
min-height = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn:min-height](https://developer.mozilla.org/en-US/docs/Web/CSS/min-height)

1. In Lynx, the priority of `max-height` is higher than `height` and `min-height`. While in Web, `max-height` overrides `height`, but `min-height` overrides `max-height`.
2. If `max-height` is specified smaller than `min-height`, `min-height` will be ignored.
3. `auto` is not supported, default value is `0px`.
4. `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.min-height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the minimum height of an element.




---
url: /api/css/properties/min-width.md
---

<APISummary />

## Introduction

To specify min width of a view. It prevents the applied value of [`width`](/api/css/properties/width.md) becoming larger than the specified value of `min-width`.
The priority of `min-width` is higher than [`width`](/api/css/properties/width.md) but lower than [`max-width`](/api/css/properties/max-width.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/min-width`
**Bundle:** `dist/min-width.lynx.bundle`

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

const MinWidth = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const firstBoxStyle = {
    width: "300px",
    backgroundColor: "green",
  };

  const secondBoxStyle = {
    width: "0px",
    backgroundColor: "yellow",
    minWidth: "300px",
  };

  const thirdBoxStyle = {
    width: "0px",
    backgroundColor: "blue",
    minWidth: "300px",
    maxWidth: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>width: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>width: 0px; min-width: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>width: 0px; min-width: 300px; max-width: 200px</text>
      </view>
    </view>
  );
};

root.render(<MinWidth />);

```



## Syntax

```css
/* <length> */
min-width: 120px;
min-width: 10em;

/* <percentage> */
min-width: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) defines the min-width as an absolute value. Default to `0px`.

#### `<percentage>`

Defines the min-width as a percentage of the containing block's width.

## Formal definition


<PropertyDefinition initialValue={<>0px</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} animatable="yes" />

## Formal syntax

```
min-width = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn:min-width](https://developer.mozilla.org/en-US/docs/Web/CSS/min-width)

1. In Lynx, the priority of `max-width` is higher than `width` and `min-width`. While in Web, `max-width` overrides `width`, but `min-width` overrides `max-width`.
2. If `max-width` is specified smaller than `min-width`, `min-width` will be ignored.
3. `auto` is not supported, default value is `0px`.
4. `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.min-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the minimum width of an element.




---
url: /api/css/properties/opacity.md
---

<APISummary />

## Introduction

The opacity CSS property sets the opacity of an element. Opacity is the degree to which content behind an element is hidden, and is the opposite of transparency.

Opacity applies to the element as a whole, including its contents, even though the value is not inherited by child elements.
Thus, the element and its children all have the same opacity relative to the element's background, even if they have different opacities relative to one another.

:::caution
The group opacity on Android is true by default, while on iOS is false. Use `overlap` and `overlap-ios` to define how opacity affects the background and contents of the view.

Group opacity will force the system to use off-screen rendering to render the view, which has performance issues on both Android and iOS.
And, on Android, the `overflow: visible` will lose effect.
:::

## Examples

**This is an example below:  css-api**

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

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

import image from "../../resource/lynx.png";

const Opacity = () => {
  const heightStyle = {
    height: "10px",
  };

  const opacity1Style = {
    opacity: 1,
  };

  const opacity05Style = {
    opacity: 0.5,
  };

  const opacity0Style = {
    opacity: 0,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <image className="relative_image" src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image" style={opacity1Style} src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image" style={opacity05Style} src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image" style={opacity0Style} src={image}></image>
      </view>
    </scroll-view>
  );
};

root.render(<Opacity />);

```



## Syntax

```css
opacity: 1;
opacity: 0.5;
opacity: 0;
```

### Values

A \<number> in the range `0.0` to `1.0`, inclusive, or a \<percentage> in the range `0%` to `100%`, inclusive, representing the opacity of the channel
(that is, the value of its alpha channel). Any value outside the interval, though valid, is clamped to the nearest limit in the range.

|                  Value                 |                                    Meaning                                    |
| :------------------------------------: | :---------------------------------------------------------------------------: |
|                    0                   |             The element is fully transparent (that is, invisible).            |
| Any \<number> strictly between 0 and 1 | The element is translucent (that is, content behind the element can be seen). |
|                    1                   |                 The element is fully opaque (visually solid).                 |

## Formal definition


<PropertyDefinition initialValue={<>1</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

opacity: `<number>`;

## Difference from Web

Opacity will affect the background and contents as a whole. For Lynx iOS should set `overlap-ios={true}`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.opacity`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/opacity](https://developer.mozilla.org/zh-CN/docs/Web/CSS/opacity)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/order.md
---

<APISummary />

## Introduction

The `order` CSS property sets the order to lay out an item in container. Items in a container are sorted by ascending order value and then by their source code order. Items not given an explicit order value are assigned the default value of `0`.

## Examples

**This is an example below:  css-api**

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

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

const Order = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const getOrderStyle = (order: number) => ({
    order: order,
  });

  return (
    <view className="intro" style={containerStyle}>
      <text className="intro-item" style={getOrderStyle(1)}>order: 1</text>
      <text className="intro-item" style={getOrderStyle(3)}>order: 3</text>
      <text className="intro-item" style={getOrderStyle(2)}>first order: 2</text>
      <text className="intro-item" style={getOrderStyle(2)}>second order: 2</text>
    </view>
  );
};

root.render(<Order />);

```



## Syntax

```css
/* Numerical value including negative numbers */
order: 5;
order: -5;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

Represents the ordinal group to be used by the item. Default value is `0`.

## Formal definition


<PropertyDefinition
  initialValue={<>0</>}
  appliesTo={
  <>
    child element with
    <Link href="/api/css/properties/position">
      <code>position: relative</code>
    </Link>
  </>
}
  inherited="no"
  animatable="no"
/>

## Difference with the Web

1. It is not supported to use on [`position: absolute/fixed/sticky`](/api/css/properties/position.md) flex and grid container children.
2. Using `order` will not influence the element's painting order in Lynx.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.order`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/order](https://developer.mozilla.org/zh-CN/docs/Web/CSS/order)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** The order CSS property sets the order to lay out an item.




---
url: /api/css/properties/overflow-x.md
---

<APISummary />

## Introduction

The overflow-x property specifies whether to clip the content when it overflows at the left and right edges.

## Examples

**This is an example below:  css-api**

**Entry:** `src/overflow-x`
**Bundle:** `dist/overflow-x.lynx.bundle`

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

const OverflowX = () => {
  const containerStyle = {
    height: "500px",
    flexDirection: "column" as const,
    justifyContent: "space-around" as const,
  };

  const firstBoxStyle = {
    overflowX: "visible",
    overflowY: "hidden",
  };

  const secondBoxStyle = {
    overflow: "hidden",
  };

  const thirdBoxStyle = {
    overflowX: "hidden",
    overflowY: "visible",
  };

  const fourthBoxStyle = {
    overflow: "hidden",
  };

  const fifthBoxStyle = {
    overflow: "visible",
  };

  return (
    <view style={containerStyle}>
      <view className="outer-box" style={firstBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={secondBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={thirdBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fourthBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fifthBoxStyle}>
        <view className="inner-box"></view>
      </view>
    </view>
  );
};

root.render(<OverflowX />);

```



## Syntax

```css
overflow-x: visible;
overflow-x: hidden;
```

### Values

- `visible`(default) the content will not be clipped, the content and the descendants may render outside the left and right edges.

- `hidden` the overflow of the content and the descendants will be clipped at the left and right edges.

## Formal definition


<PropertyDefinition initialValue={<>visible</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
hidden | visible
```

## Difference from Web

- `overflow` does not contain `scroll` and `auto`, for `scroll` please use [`<scroll-view>`](/api/elements/built-in/scroll-view.md) directly.

## Notes

- On Android platform, the Android view that has `opacity < 1` will be rendered in an offscreen buffer by default, the offscreen makes the `overflow-x :visible` not work correctly, you can add `overlap={false}` to disable the offscreen rendering. The property is linked to Android View `hasOverlappingRendering` property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.overflow-x`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-x](https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-x)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/overflow-y.md
---

<APISummary />

## Introduction

The overflow-y property specifies whether to clip the content when it overflows at the top and bottom edges.

## Examples

**This is an example below:  css-api**

**Entry:** `src/overflow-y`
**Bundle:** `dist/overflow-y.lynx.bundle`

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

const OverflowY = () => {
  const containerStyle = {
    height: "500px",
    flexDirection: "column" as const,
    justifyContent: "space-around" as const,
  };

  const firstBoxStyle = {
    overflowX: "visible",
    overflowY: "hidden",
  };

  const secondBoxStyle = {
    overflow: "hidden",
  };

  const thirdBoxStyle = {
    overflowX: "hidden",
    overflowY: "visible",
  };

  const fourthBoxStyle = {
    overflow: "hidden",
  };

  const fifthBoxStyle = {
    overflow: "visible",
  };

  return (
    <view style={containerStyle}>
      <view className="outer-box" style={firstBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={secondBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={thirdBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fourthBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fifthBoxStyle}>
        <view className="inner-box"></view>
      </view>
    </view>
  );
};

root.render(<OverflowY />);

```



## Syntax

```css
overflow-y: visible;
overflow-y: hidden;
```

### Values

- `visible`(default) the content will not be clipped, the content and the descendants may render outside the top and bottom edges.

- `hidden` the overflow of the content and the descendants will be clipped at the top and bottom edges.

## Formal definition


<PropertyDefinition initialValue={<>visible</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
hidden | visible
```

## Difference from Web

- `overflow` does not contain `scroll` and `auto`, for `scroll` please use [`<scroll-view>`](/api/elements/built-in/scroll-view.md) directly.

## Notes

- On Android platform, the Android view that has `opacity < 1` will be rendered in an offscreen buffer by default, the offscreen makes the `overflow-y: visible` not work correctly, you can add `overlap={false}` to disable the offscreen rendering. The property is linked to Android View `hasOverlappingRendering` property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.overflow-y`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-y](https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-y)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/overflow.md
---

<APISummary />

## Introduction

The overflow property specifies whether to clip the content when the content of an element is too big.

:::caution

- It's recommended to set `overflow: hidden` explicitly, if the node is not need to be overflow; On Android platform, the re-drawn region may become larger than view‘s rect when `overflow: visible`.

:::

## Examples

**This is an example below:  css-api**

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

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

const Overflow = () => {
  const containerStyle = {
    height: "500px",
    flexDirection: "column" as const,
    justifyContent: "space-around" as const,
  };

  const firstBoxStyle = {
    overflowX: "visible",
    overflowY: "hidden",
  };

  const secondBoxStyle = {
    overflow: "hidden",
  };

  const thirdBoxStyle = {
    overflowX: "hidden",
    overflowY: "visible",
  };

  const fourthBoxStyle = {
    overflow: "hidden",
  };

  const fifthBoxStyle = {
    overflow: "visible",
  };

  return (
    <view style={containerStyle}>
      <view className="outer-box" style={firstBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={secondBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={thirdBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fourthBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fifthBoxStyle}>
        <view className="inner-box"></view>
      </view>
    </view>
  );
};

root.render(<Overflow />);

```



## Syntax

```css
overflow: visible;
overflow: hidden;
```

### Values

- `visible`(default) the content will not be clipped, the content and the descendants may render outside the element box

- `hidden` the overflow of the content and the descendants will be clipped, the reset of the content will be visible

## Formal definition


<PropertyDefinition initialValue={<>visible</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
hidden | visible
```

## Difference from Web

- `overflow` does not contain `scroll` and `auto`, for `scroll` please use [`<scroll-view>`](/api/elements/built-in/scroll-view.md) directly.

## Notes

- On Android platform, the Android view that has `opacity < 1` will be rendered in an offscreen buffer by default, the offscreen makes the `overflow: visible` not work correctly, you can add `overlap={false}` to disable the offscreen rendering. The property is linked to Android View `hasOverlappingRendering` property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.overflow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-bottom.md
---

<APISummary />

## Introduction

Sets the height of the padding area on the bottom of an element. Negative values are not allowed for padding.

## Examples

**This is an example below:  css-api**

**Entry:** `src/padding-bottom`
**Bundle:** `dist/padding-bottom.lynx.bundle`

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

const PaddingBottom = () => {
  const containerStyle = {
    paddingTop: "10px",
    paddingBottom: "30px",
  };

  return (
    <view className="con" style={containerStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingBottom />);

```



## Syntax

```css
/* <length> values */
padding-bottom: 0.5em;
padding-bottom: 0;

/* <percentage> value */
padding-bottom: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
padding-bottom =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-inline-end.md
---

<APISummary />

## Introduction

Defines the logical inline end padding of an element, which maps to a physical padding depending on the element's [`direction`](/api/css/properties/direction.md). Must be nonnegative.

In `LTR` mode, `padding-inline-end` taking the same values as the [`padding-right`](/api/css/properties/padding-right.md).
In `RTL` mode, `padding-inline-end` taking the same values as the [`padding-left`](/api/css/properties/padding-left.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/padding-inline-end`
**Bundle:** `dist/padding-inline-end.lynx.bundle`

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

const PaddingInlineEnd = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
    paddingInlineStart: "10px",
    paddingInlineEnd: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro">1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<PaddingInlineEnd />);

```



## Syntax

```css
/* <length> values */
padding-inline-end: 0.5em;
padding-inline-end: 0px;
padding-inline-end: 2rpx;

/* <percentage> value */
padding-inline-end: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
padding-inline-end =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

1. `writing mode` is not supported in Lynx.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-inline-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-inline-start.md
---

<APISummary />

## Introduction

Defines the logical inline start padding of an element, which maps to a physical padding depending on the element's [`direction`](/api/css/properties/direction.md). Must be nonnegative.

In `LTR` mode, `padding-inline-start` taking the same values as the [`padding-left`](/api/css/properties/padding-left.md).
In `RTL` mode, `padding-inline-start` taking the same values as the [`padding-right`](/api/css/properties/padding-right.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/padding-inline-start`
**Bundle:** `dist/padding-inline-start.lynx.bundle`

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

const PaddingInlineStart = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
    paddingInlineStart: "10px",
    paddingInlineEnd: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro">1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<PaddingInlineStart />);

```



## Syntax

```css
/* <length> values */
padding-inline-start: 0.5em;
padding-inline-start: 0px;
padding-inline-start: 2rpx;

/* <percentage> value */
padding-inline-start: 10%;
```

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} />

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal syntax

```
padding-inline-start =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

1. `writing mode` is not supported in Lynx.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-inline-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-left.md
---

<APISummary />

## Introduction

Sets the width of the padding area on the left of an element. Negative values are not allowed for padding.

## Examples

**This is an example below:  css-api**

**Entry:** `src/padding-left`
**Bundle:** `dist/padding-left.lynx.bundle`

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

const PaddingLeft = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
    background: "white",
  };

  const contentStyle = {
    paddingLeft: "10px",
    paddingRight: "30px",
  };

  return (
    <view className="con" style={contentStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingLeft />);

```



## Syntax

```css
/* <length> values */
padding-left: 0.5em;
padding-left: 0;

/* <percentage> value */
padding-left: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} animatable="yes" />

## Formal syntax

```
padding-left =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-right.md
---

<APISummary />

## Introduction

Sets the width of the padding area on the right of an element. Negative values are not allowed for padding.

## Examples

**This is an example below:  css-api**

**Entry:** `src/padding-right`
**Bundle:** `dist/padding-right.lynx.bundle`

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

import imageUrl from "../../resource/lynx.png";

const PaddingRight = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
    background: "white",
  };

  const contentStyle = {
    paddingLeft: "10px",
    paddingRight: "30px",
  };

  return (
    <view className="con" style={contentStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingRight />);

```



## Syntax

```css
/* <length> values */
padding-right: 0.5em;
padding-right: 0;

/* <percentage> value */
padding-right: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} animatable="yes" />

## Formal syntax

```
padding-right =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-top.md
---

<APISummary />

## Introduction

Sets the height of the padding area on the top of an element. Negative values are not allowed for padding.

## Examples

**This is an example below:  css-api**

**Entry:** `src/padding-top`
**Bundle:** `dist/padding-top.lynx.bundle`

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

import imageUrl from "../../resource/lynx.png";

const PaddingTop = () => {
  const containerStyle = {
    paddingTop: "10px",
    paddingBottom: "30px",
  };

  return (
    <view className="con" style={containerStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingTop />);

```



## Syntax

```css
/* <length> values */
padding-top: 0.5em;
padding-top: 0;

/* <percentage> value */
padding-top: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} animatable="yes" />

## Formal syntax

```
padding-top =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding.md
---

<APISummary />

## Introduction

Sets the padding area on all four sides of an element at once. An element's padding area is the space between its content and its border.

This property is a shorthand for the following CSS properties: [`padding-top`](/api/css/properties/padding-top.md), [`padding-right`](/api/css/properties/padding-right.md)、[`padding-bottom`](/api/css/properties/padding-bottom.md), [`padding-left`](/api/css/properties/padding-left.md).

## Examples

**This is an example below:  css-api**

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

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

const Padding = () => {
  const scrollViewStyle = {
    flexDirection: "column" as const,
    width: "100%",
    height: "100%",
  };

  const firstBoxStyle = {
    padding: "20px",
  };

  const secondBoxStyle = {
    padding: "20px 5px",
  };

  const thirdBoxStyle = {
    padding: "20px 15px 10px",
  };

  const fourthBoxStyle = {
    padding: "20px 15px 10px 5px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <view className="intro" style={firstBoxStyle}>
          <text className="intro2">padding: 20px; All sides</text>
        </view>
      </view>

      <view className="con">
        <view className="intro" style={secondBoxStyle}>
          <text className="intro2">padding: 20px 5px; Top/Bottom | Left/Right</text>
        </view>
      </view>

      <view className="con">
        <view className="intro" style={thirdBoxStyle}>
          <text className="intro2">padding: 20px 15px 10px; Top | Left/Right | Bottom</text>
        </view>
      </view>

      <view className="con">
        <view className="intro" style={fourthBoxStyle}>
          <text className="intro2">padding: 20px 15px 10px 5px; Top | Right | Bottom | Left</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Padding />);

```



## Syntax

```css
/* Apply to all four sides */
padding: 1em;

/* top and bottom | left and right */
padding: 5% 10%;

/* top | left and right | bottom */
padding: 1em 2em 2em;

/* top | right | bottom | left */
padding: 5px 1em 0 2em;
```

The padding property may be specified using one, two, three, or four values. Each value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md). Negative values are invalid.

When one value is specified, it applies the same padding to all four sides.
When two values are specified, the first padding applies to the top and bottom, the second to the left and right.
When three values are specified, the first padding applies to the top, the second to the right and left, the third to the bottom.
When four values are specified, the paddings apply to the top, right, bottom, and left in that order (clockwise).

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    as each of the properties of the shorthand: <br />
    <ul style={{ listStyleType: 'disc', paddingLeft: '1.5rem' }}>
      <li>padding-bottom: 0</li>
      <li>padding-left: 0</li>
      <li>padding-right: 0</li>
      <li>padding-top: 0</li>
    </ul>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  percentages={<>refer to the width of the containing block</>}
/>

## Formal syntax

```
padding =
  <'padding-top'>{1,4}

<padding-top> =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/perspective.md
---

<APISummary />

## Introduction

The perspective CSS property determines the distance between the z=0 plane and the user in order to give a 3D-positioned element some perspective.

## Examples

**This is an example below:  css-api**

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

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

const Perspective = () => {
  const [front, setFront] = useState(false);
  const [enableAni, setEnableAni] = useState(false);

  const handleKeyframe = () => {
    setFront(!front);
  };

  const handleAni = () => {
    setEnableAni(!enableAni);
  };

  const containerStyle = {
    display: "flex" as const,
    flexDirection: "column" as const,
    width: "100%",
    height: "1000px",
    background: "white",
  };

  const perspectiveStyle = {
    perspective: "750px",
  };

  return (
    <view style={containerStyle}>
      <text>Animation demo</text>

      <view className={front ? "container front" : "container back"} style={perspectiveStyle} bindtap={handleKeyframe}>
        <text>Front</text>
      </view>
      <view
        className={front ? "container1 back" : "container1 front"}
        style={perspectiveStyle}
        bindtap={handleKeyframe}
      >
        <view className="container2" />
        <text>Back</text>
      </view>
      <view className="anim-container">
        <view
          className={enableAni ? "anim-content anim-content-back backf0" : "anim-content anim-content-back backf1"}
          style={perspectiveStyle}
          bindtap={handleAni}
        >
          <text>Front</text>
          <text>Back</text>
        </view>
        <view
          className={enableAni ? "anim-content anim-content-front keyf0" : "anim-content anim-content-front keyf1"}
          style={perspectiveStyle}
          bindtap={handleAni}
        >
          <text>back</text>
        </view>
      </view>
    </view>
  );
};

root.render(<Perspective />);

```



## Syntax

```css
/* Keyword value */
perspective: auto;

/* <length> values */
perspective: 20px;
perspective: 3.5em;
```

### Values

- `auto`
  Default value

- `[<length>]`
  specifies the observer's distance from the `z=0` plane

```
perspective = auto | <length [0,∞]>
```

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
perspective = auto | <length [0,∞]>
```

## Differences from Web

- Different from Web, the Perspective property in Lynx takes effect on the current node, while in Web, the Perspective property takes effect on child nodes.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.perspective`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/perspective](https://developer.mozilla.org/zh-CN/docs/Web/CSS/perspective)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | It takes effect on all its descendants. |




---
url: /api/css/properties/pointer-events.md
---

# pointer-events

<APISummary />

## Introduction

The `pointer-events` CSS property specifies whether a component can respond to touch events.

## Usage Examples

**This is an example below:  css-api**

**Entry:** `src/pointer-events`
**Bundle:** `dist/pointer-events.lynx.bundle`

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

const PointerEvents = () => {
  const [bgColor, setBgColor] = useState("white");
  const [isShow, setIsShow] = useState(false);

  function handleControlTap(e: TouchEvent) {
    "background-only";
    setIsShow(isShow => !isShow);
  }

  function handleContentTap(e: TouchEvent) {
    "background-only";
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    setBgColor(rndCol);
  }

  return (
    <view className="container">
      <view className="control" bindtap={handleControlTap}>
        <text style={{ fontSize: "18px" }}>show or close popup</text>
      </view>
      {isShow
        && (
          <view className="popup" style={{ pointerEvents: "none" }}>
            <view className="mask">
              <view
                className="content"
                style={{ backgroundColor: bgColor, pointerEvents: "auto" }}
                bindtap={handleContentTap}
              />
            </view>
          </view>
        )}
    </view>
  );
};

root.render(<PointerEvents />);

```



## Syntax

```css
pointer-events: auto;
pointer-events: none;
```

### Values

- `auto`

  Default value. In this case, the node can respond to touch events.

- `none`

  The node cannot respond to touch events.

## Formal Definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>all elements that don't override hitTest </>} inherited="no" animatable="no" />

## Formal Syntax

```
pointer-events: auto | none;
```

## Differences from Web

`inherit`, `initial`, and `unset` are not supported. There are no `SVG only` attribute values ​​such as `visiblePaintedroll` and `visibleFill`.

## Notes

- This property has an inheritance effect, that is, when the child node does not set `pointer-events`, it will inherit the `pointer-events` value of the parent node.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.pointer-events`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/pointer-events](https://developer.mozilla.org/zh-CN/docs/Web/CSS/pointer-events)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |
| HarmonyOS | 3.5 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ❌ No | - |




---
url: /api/css/properties/position.md
---

<APISummary />

## Introduction

The `position` CSS property sets how an element is positioned in a document. The [`top`](/api/css/properties/top.md), [`right`](/api/css/properties/right.md), [`bottom`](/api/css/properties/bottom.md), and [`left`](/api/css/properties/left.md) properties determine the final location of positioned elements.

## Types of positioning

- A positioned element is an element whose computed position value is either `relative`, `absolute`, `fixed`, or `sticky`.

- A relatively positioned element is an element whose computed position value is relative. The [`top`](/api/css/properties/top.md) and [`bottom`](/api/css/properties/bottom.md) properties specify the vertical offset from its normal position; the [`left`](/api/css/properties/left.md) and [`right`](/api/css/properties/right.md)properties specify the horizontal offset.

- An absolutely positioned element is an element whose computed position value is `absolute` or `fixed`. The `top`, `right`, `bottom`, and `left` properties specify offsets from the edges of the element's containing block. (The containing block is the ancestor relative to which the element is positioned.) If the element has margins, they are added to the offset. The element establishes a new block formatting context (BFC) for its contents.

- A stickily positioned element is an element whose computed position value is sticky. It's treated as relatively positioned until its containing block crosses a specified threshold (such as setting top to value other than auto) within its flow root (or the container it scrolls within), at which point it is treated as "stuck" until meeting the opposite edge of its containing block.

Most of the time, absolutely positioned elements that have [`height`](/api/css/properties/height.md) and [`width`](/api/css/properties/width.md) set to auto are sized so as to fit their contents. However, absolutely positioned elements can be made to fill the available vertical space by specifying both `top` and `bottom` and leaving `height` unspecified (that is, `auto`). They can likewise be made to fill the available horizontal space by specifying both `left` and `right` and leaving width as `auto`.

Except for the case just described (of absolutely positioned elements filling the available space):

If both `top` and `bottom` are specified (technically, not auto), `top` wins.
If both `left` and `right` are specified, `left` wins when direction is `ltr` (English, horizontal Japanese, etc.) and `right` wins when `direction` is `rtl` (Persian, Arabic, Hebrew, etc.).

## Examples

**This is an example below:  css-api**

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

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

const Position = () => {
  const boxStyles = {
    fixed1: {
      position: "fixed" as const,
      top: "5px",
      left: "5px",
      width: "50px",
      height: "50px",
      backgroundColor: "red",
    },
    absolute1: {
      position: "absolute" as const,
      top: "0px",
      left: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "brown",
    },
    fixed2: {
      position: "fixed" as const,
      top: "5px",
      left: "105px",
      width: "50px",
      height: "50px",
      backgroundColor: "pink",
    },
    absolute2: {
      position: "absolute" as const,
      right: "0px",
      width: "50px",
      height: "50px",
      backgroundColor: "coral",
    },
    fixed3: {
      position: "fixed" as const,
      left: "5px",
      top: "55px",
      width: "50px",
      height: "50px",
      backgroundColor: "Chocolate",
    },
    absolute3: {
      position: "absolute" as const,
      left: "100px",
      top: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkOrange",
    },
    absolute4: {
      position: "absolute" as const,
      top: "50px",
      left: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "yellow",
    },
    absolute5: {
      position: "absolute" as const,
      left: "150px",
      top: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "GoldenRod",
    },
    absolute6: {
      position: "absolute" as const,
      left: "0px",
      top: "100px",
      width: "50px",
      height: "50px",
      backgroundColor: "GreenYellow",
    },
    absolute7: {
      position: "absolute" as const,
      left: "50px",
      top: "100px",
      width: "50px",
      height: "50px",
      backgroundColor: "LightBlue",
    },
    absolute8: {
      position: "absolute" as const,
      left: "150px",
      top: "100px",
      width: "50px",
      height: "50px",
      backgroundColor: "DodgerBlue",
    },
    absolute9: {
      position: "absolute" as const,
      left: "0px",
      top: "150px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkTurquoise",
    },
    fixed4: {
      position: "fixed" as const,
      left: "55px",
      top: "155px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkSlateBlue",
    },
    fixed5: {
      position: "fixed" as const,
      left: "105px",
      top: "155px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkSlateGrey",
    },
    absolute10: {
      position: "absolute" as const,
      bottom: "50px",
      right: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "green",
    },
    fixed6: {
      position: "fixed" as const,
      top: "155px",
      left: "155px",
      width: "50px",
      height: "50px",
      backgroundColor: "blue",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view style={boxStyles.fixed1}></view>
          <view style={boxStyles.absolute1}></view>
          <view style={boxStyles.fixed2}></view>
          <view style={boxStyles.absolute2}></view>
          <view style={boxStyles.fixed3}></view>
          <view style={boxStyles.absolute3}></view>
          <view style={boxStyles.absolute4}></view>
          <view style={boxStyles.absolute5}></view>
          <view style={boxStyles.absolute6}></view>
          <view style={boxStyles.absolute7}></view>
          <view style={boxStyles.absolute8}></view>
          <view style={boxStyles.absolute9}></view>
          <view style={boxStyles.fixed4}></view>
          <view style={boxStyles.fixed5}></view>
          <view style={boxStyles.absolute10}></view>
          <view style={boxStyles.fixed6}></view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Position />);

```



## Syntax

```css
position: relative;
position: fixed;
position: absolute;
position: sticky;
```

### Values

#### `relative`

**default value**. The element is positioned according to the normal flow of the document, and then offset relative to itself based on the values of `top`, `right`, `bottom`, and `left`. The offset does not affect the position of any other elements.

#### `absolute`

The element is removed from the normal document flow, and no space is created for the element in the page layout. It is positioned relative to the containing block of its parent element. Its final position is determined by the values of `top`, `right`, `bottom`, and `left`.

#### `fixed`

The element is will be treated as a direct child of root node with the property `position` as `absolute`. Its final position is determined by the values of top, right, bottom, and left.

#### `sticky`

`sticky` is only supported on the children elements of a `scroll-view`. Is The element is positioned according to the normal flow of the document, and then offset relative to its parent scroll-view and containing block (nearest block-level ancestor), based on the values of top, right, bottom, and left. The offset does not affect the position of any other elements.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>relative</code>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  animatable="no"
/>

## Formal syntax

## Difference with the Web

[mdn:position](https://developer.mozilla.org/en-US/docs/Web/CSS/position)

1. Lynx does not support `static` and default value is `relative`.
2. `sticky` is only supported on the children elements of a `scroll-view`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.position`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/position](https://developer.mozilla.org/zh-CN/docs/Web/CSS/position)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |


## FAQ

1. If using [`z-index`](/api/css/properties/z-index.md) in `position: absolute` element, please set `z-index: 0` in parent element at the same time.



---
url: /api/css/properties/relative-align-bottom.md
---

<APISummary />

## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the bottom edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-align-bottom`
**Bundle:** `dist/relative-align-bottom.lynx.bundle`

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

const RelativeAlignBottom = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeAlignBottom: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeAlignBottom: "parent" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-align-bottom: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-align-bottom: parent</text>
      </view>
    </view>
  );
};

root.render(<RelativeAlignBottom />);

```



## Syntax

```css
relative-align-bottom: parent;
relative-align-bottom: none;

relative-align-bottom: 1;
relative-align-bottom: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the bottom edge.

- `parent`

  The bottom edge is aligned with the parent element.

- `<number>`

  `int` only. The bottom edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-align-bottom = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-bottom`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the bottom edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-inline-end.md
---

<APISummary />

## Introduction

Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-align-inline-end` is equivalent to [`relative-align-right`](/api/css/properties/relative-align-right.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`,`relative-align-inline-end` is equivalent to [`relative-align-left`](/api/css/properties/relative-align-left.md);

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-align-inline-end`
**Bundle:** `dist/relative-align-inline-end.lynx.bundle`

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

const RelativeAlignInlineEnd = () => {
  const container1Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "ltr" as const,
    marginBottom: "20px" as const,
  };
  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignInlineEnd: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignInlineEnd: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={container1Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-end: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-end: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-end: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-end: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignInlineEnd />);

```



## Syntax

```css
relative-align-inline-end: parent;
relative-align-inline-end: none;

relative-align-inline-end: 1;
relative-align-inline-end: 2;
```

### Values

The `relative-align-inline-end` property takes the same values as the [`relative-align-left`](/api/css/properties/relative-align-left.md) property.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-align-inline-end = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-inline-end`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-inline-start.md
---

<APISummary />

## Introduction

Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-align-inline-start` is equivalent to [`relative-align-left`](/api/css/properties/relative-align-left.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`,`relative-align-inline-start` is equivalent to [`relative-align-right`](/api/css/properties/relative-align-right.md);

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-align-inline-start`
**Bundle:** `dist/relative-align-inline-start.lynx.bundle`

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

const RelativeAlignInlineStart = () => {
  const container1Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "ltr" as const,
    marginBottom: "20px" as const,
  };
  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignInlineStart: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignInlineStart: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={container1Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-start: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-start: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-start: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-start: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignInlineStart />);

```



## Syntax

```css
relative-align-inline-start: parent;
relative-align-inline-start: none;

relative-align-inline-start: 1;
relative-align-inline-start: 2;
```

### Values

The `relative-align-inline-start` property takes the same values as the [`relative-align-left`](/api/css/properties/relative-align-left.md) property.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-align-inline-start = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-inline-start`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-left.md
---

<APISummary />

## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the left edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-align-left`
**Bundle:** `dist/relative-align-left.lynx.bundle`

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

const RelativeAlignLeft = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignLeft: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignLeft: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "40rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-left: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-left: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignLeft />);

```



## Syntax

```css
relative-align-left: parent;
relative-align-left: none;

relative-align-left: 1;
relative-align-left: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the left edge.

- `parent`

  The left edge is aligned with the parent element.

- `<number>`

  `int` only. The left edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-align-left = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-left`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the left edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-right.md
---

<APISummary />

## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the right edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-align-right`
**Bundle:** `dist/relative-align-right.lynx.bundle`

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

const RelativeAlignRight = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignRight: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignRight: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "40rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-right: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-right: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignRight />);

```



## Syntax

```css
relative-align-right: parent;
relative-align-right: none;

relative-align-right: 1;
relative-align-right: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the right edge.

- `parent`

  The right edge is aligned with the parent element.

- `<number>`

  `int` only. The right edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-align-right = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-right`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the right edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-top.md
---

<APISummary />

## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the top edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-align-top`
**Bundle:** `dist/relative-align-top.lynx.bundle`

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

const RelativeAlignTop = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeAlignTop: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeAlignTop: "parent" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-align-top: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-align-top: parent</text>
      </view>
    </view>
  );
};

root.render(<RelativeAlignTop />);

```



## Syntax

```css
relative-align-top: parent;
relative-align-top: none;

relative-align-top: 1;
relative-align-top: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the top edge.

- `parent`

  The top edge is aligned with the parent element.

- `<number>`

  `int` only. The top edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-align-top = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-top`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the top edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-bottom-of.md
---

<APISummary />

## Introduction

The current element is to the below of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-bottom-of`
**Bundle:** `dist/relative-bottom-of.lynx.bundle`

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

const RelativeBottomOf = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeBottomOf: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeBottomOf: "1" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-bottom-of: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-bottom-of: 1</text>
      </view>
    </view>
  );
};

root.render(<RelativeBottomOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-bottom-of: none;
relative-bottom-of: 1;
relative-bottom-of: 2;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-bottom-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-bottom-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the bottom of the sibling element specified corresponding to id.




---
url: /api/css/properties/relative-center.md
---

<APISummary />

## Introduction

Used to set the centering alignment of the current element in the [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below:  css-api**

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

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

const RelativeCenter = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const view1Style = {
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen" as const,
  };

  const view2Style = {
    relativeCenter: "vertical" as const,
    backgroundColor: "lightblue" as const,
  };

  const view3Style = {
    relativeCenter: "both" as const,
    backgroundColor: "yellow" as const,
  };

  const view4Style = {
    relativeCenter: "none" as const,
    backgroundColor: "pink" as const,
  };

  const textStyle = {
    fontSize: "70rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>horizontal</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>vertical</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>both</text>
      </view>
      <view style={view4Style}>
        <text style={textStyle}>none</text>
      </view>
    </view>
  );
};

root.render(<RelativeCenter />);

```



## Value

### `none`

**Default Value**. Not centered.

### `both`

Centered vertically and horizontally.

### `vertical`

Center vertically.

### `horizontal`

Centered horizontally.

## Syntax

```css
relative-center: none;
relative-center: both;
relative-center: vertical;
relative-center: horizontal;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-center = none | both | vertical | horizontal
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-center`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the bottom edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-id.md
---

<APISummary />

## Introduction

Used to set the number of sibling elements in the [relative-layout](/guide/ui/layout/relative-layout.md). `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.

## Examples

**This is an example below:  css-api**

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

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

const RelativeId = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const view1Style = {
    relativeId: "1",
    backgroundColor: "lightgreen",
  };

  const view2Style = {
    relativeRightOf: "1",
    relativeId: "2",
    backgroundColor: "lightblue",
  };

  const view3Style = {
    relativeId: "3",
    relativeCenter: "vertical" as const,
    backgroundColor: "yellow",
  };

  const view4Style = {
    relativeRightOf: "3",
    relativeId: "4",
    relativeCenter: "vertical" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "50rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>relative-id: 1</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>relative-id: 2</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>relative-id: 3</text>
      </view>
      <view style={view4Style}>
        <text style={textStyle}>relative-id: 4</text>
      </view>
    </view>
  );
};

root.render(<RelativeId />);

```



## Values

### `<number>`

`int` only. the number of the current element. **Default value** is `-1`.

`-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.

## Syntax

```css
relative-id: 1;
relative-id: 2;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>-1</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-id = <integer [1,∞]>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-id`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Used to set the number of sibling elements in the relative layout.




---
url: /api/css/properties/relative-inline-end-of.md
---

<APISummary />

## Introduction

The current element is to the left/right of the sibling element corresponding to the specified [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-inline-end-of` is equivalent to [`relative-right-of`](/api/css/properties/relative-right-of.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`, `relative-inline-end-of` is equivalent to [`relative-left-of`](/api/css/properties/relative-left-of.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-inline-end-of`
**Bundle:** `dist/relative-inline-end-of.lynx.bundle`

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

const RelativeInlineEndOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
    direction: "ltr" as const,
  };

  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeCenter: "horizontal" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeInlineEndOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeInlineEndOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "23rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeInlineEndOf />);

```



## Values

The `relative-inline-end-of` property takes the same values as the [`relative-left-of`](/api/css/properties/relative-left-of.md).

## Syntax

```css
relative-inline-end-of: none;
relative-inline-end-of: 1;
relative-inline-end-of: 2;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-inline-end-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-inline-end-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** The current element is to the left/right of the sibling element corresponding to the specified id.




---
url: /api/css/properties/relative-inline-start-of.md
---

<APISummary />

## Introduction

The current element is to the left/right of the sibling element corresponding to the specified [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-inline-start-of` is equivalent to [`relative-left-of`](/api/css/properties/relative-left-of.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`, `relative-inline-start-of` is equivalent to [`relative-right-of`](/api/css/properties/relative-right-of.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-inline-start-of`
**Bundle:** `dist/relative-inline-start-of.lynx.bundle`

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

const RelativeInlineStartOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
    direction: "ltr" as const,
  };

  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeCenter: "horizontal" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeInlineStartOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeInlineStartOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "23rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeInlineStartOf />);

```



## Values

The `relative-inline-start-of` property takes the same values as the [`relative-left-of`](/api/css/properties/relative-left-of.md).

## Syntax

```css
relative-inline-start-of: none;
relative-inline-start-of: 1;
relative-inline-start-of: 2;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-inline-start-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-inline-start-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** The current element is to the left/right of the sibling element corresponding to the specified id.




---
url: /api/css/properties/relative-layout-once.md
---

<APISummary />

## Introduction

Used to set typesetting acceleration in [relative-layout](/guide/ui/layout/relative-layout.md).
When using positioning between elements at the same level, it is recommended to enable this property, and elements at the same level will only depend upwards.

When this property is false, the relative performance is poor, and it can support the vertical direction and handle the dependencies separately in the horizontal direction.
For example, if there are 1 and 2 elements in the page, the width of 1 is determined by 2, and the height of 2 is determined by 1. In this case, if relative-layout-once is true, it cannot be processed, and relative-layout-once is false. can be handled.

## Syntax

```css
relative-layout-once: true;
relative-layout-once: false;
```

### Values

- `true`

  **Default Value**. Turn on [relative-layout](/guide/ui/layout/relative-layout.md) acceleration.

- `false`

  Turn off [relative](/guide/ui/layout/relative-layout.md) layout acceleration.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>true</code>
  </>
}
  appliesTo={<>relative container</>}
  inherited="no"
/>

## Formal syntax

```
relative-layout-once = true | false
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-layout-once`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Used to set typesetting acceleration. When using positioning between elements at the same level, it is recommended to enable this property, and elements at the same level will only depend upwards.




---
url: /api/css/properties/relative-left-of.md
---

<APISummary />

## Introduction

The current element is to the left of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-left-of`
**Bundle:** `dist/relative-left-of.lynx.bundle`

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

const RelativeLeftOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginTop: "20px" as const,
    marginBottom: "20px" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeAlignRight: "parent" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeLeftOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeLeftOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "25rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>relative-id: 1</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>relative-left-of: 1</text>
        <text style={textStyle}>relative-align-bottom: parent</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>relative-left-of: 1</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
    </view>
  );
};

root.render(<RelativeLeftOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-left-of: none;
relative-left-of: 1;
relative-left-of: 2;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-left-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-left-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the left of the sibling element specified corresponding to id.




---
url: /api/css/properties/relative-right-of.md
---

<APISummary />

## Introduction

The current element is to the right of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-right-of`
**Bundle:** `dist/relative-right-of.lynx.bundle`

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

const RelativeRightOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginTop: "20px" as const,
    marginBottom: "20px" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeAlignLeft: "parent" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeRightOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeRightOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "25rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>relative-id: 1</text>
        <text style={textStyle}>relative-align-left: parent</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>relative-right-of: 1</text>
        <text style={textStyle}>relative-align-bottom: parent</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>relative-right-of: 1</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
    </view>
  );
};

root.render(<RelativeRightOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-right-of: none;
relative-right-of: 1;
relative-right-of: 2;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-right-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-right-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the right of the sibling element specified corresponding to id.




---
url: /api/css/properties/relative-top-of.md
---

<APISummary />

## Introduction

The current element is to the top of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below:  css-api**

**Entry:** `src/relative-top-of`
**Bundle:** `dist/relative-top-of.lynx.bundle`

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

const RelativeTopOf = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeTopOf: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeTopOf: "1" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-top-of: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-top-of: 1</text>
      </view>
    </view>
  );
};

root.render(<RelativeTopOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-top-of: none;
relative-top-of: 1;
relative-top-of: 2;
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>none</code>
  </>
}
  appliesTo={<>relative items</>}
  inherited="no"
/>

## Formal syntax

```
relative-top-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-top-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the top of the sibling element specified corresponding to id.




---
url: /api/css/properties/right.md
---

<APISummary />

## Introduction

The `right` CSS property participates in specifying the horizontal position of a positioned element. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `right` depends on how the element is positioned (i.e., the value of the position property):

- When `position` is set to `absolute` or `fixed`, the `right` property specifies the distance between the element's outer margin of `right` edge and the inner border of the `right` edge of its containing block.

- When `position` is set to `relative`, the `right` property specifies the distance the element's `right` edge is moved to the `left` from its normal position.

When both `left` and `right` are defined, and `width` constraints don't prevent it, the element will stretch to satisfy both. If the element cannot stretch to satisfy both, the `position` of the element is overspecified. When this is the case, the `left` value has precedence when the container is left-to-right; the `right` value has precedence when the container is right-to-left.

## Examples

**This is an example below:  css-api**

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

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

const Right = () => {
  const containerStyle = {
    width: "210px",
    height: "210px",
    border: "5px",
    borderColor: "black",
  };

  const firstBoxStyle = {
    position: "absolute" as const,
    right: "80px",
    width: "50px",
    height: "50px",
    backgroundColor: "red",
  };

  const secondBoxStyle = {
    position: "fixed" as const,
    right: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "green",
  };

  const thirdBoxStyle = {
    position: "relative" as const,
    right: "40px",
    width: "50px",
    height: "50px",
    backgroundColor: "yellow",
  };

  const fourthBoxStyle = {
    width: "50px",
    height: "50px",
    backgroundColor: "blue",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={containerStyle}>
        <view style={firstBoxStyle}></view>
        <view style={secondBoxStyle}></view>
        <view style={thirdBoxStyle}></view>
        <view style={fourthBoxStyle}></view>
      </view>
    </scroll-view>
  );
};

root.render(<Right />);

```



## Syntax

```css
/* <length> values */
right: 3px;
right: 2rpx;
right: 2.4em;
right: 3rem;

right: 10%;

/* Keyword value */
right: auto;

/* calc */
right: calc(1px + 1px);
```

### Values

#### `auto`

**Default value**.

#### `<length>`

A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

- for absolutely positioned elements, the distance to the right edge of the containing block.

- for relatively positioned elements, the distance that the element is moved to the left of its normal position.

#### `<percentage>`

A `<percentage>` of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s width.

## Formal definition


<PropertyDefinition initialValue={<>auto</>} appliesTo={<>all elements</>} inherited="no" percentages={<>refer to the width of the containing block</>} />

## Formal syntax

```
right =
  auto                 |
  <length-percentage>  |

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** participates in setting the horizontal position of a positioned element. It has no effect on non-positioned elements.




---
url: /api/css/properties/row-gap.md
---

<APISummary />

## Introduction

The `row-gap`/`grid-row-gap` CSS property sets the size of the gap (gutter) between an element's rows in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) and grid layout.

For compatibility, `row-gap` or `grid-row-gap` can be used both.

## Examples

**This is an example below:  css-api**

**Entry:** `src/row-gap`
**Bundle:** `dist/row-gap.lynx.bundle`

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

const RowGap = () => {
  const flexContainerStyle = {
    display: "flex" as const,
    flexWrap: "wrap" as const,
    rowGap: "15px",
    margin: "10px",
    border: "1px solid #000",
    borderRadius: "4px",
    marginBottom: "100rpx" as const,
  };

  const gridContainerStyle = {
    display: "grid" as const,
    rowGap: "10px",
    gridTemplateColumns: "1fr 1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>using row-gap in flex layout</text>
      <view style={flexContainerStyle}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
        <text className="item">SIX</text>
        <text className="item">SEVEN</text>
        <text className="item">EIGHT</text>
        <text className="item">NINE</text>
        <text className="item">TEN</text>
      </view>

      <text style={titleStyle}>using row-gap in grid layout</text>
      <view style={gridContainerStyle}>
        <text className="item2">ONE</text>
        <text className="item2">TWO</text>
        <text className="item2">THREE</text>
        <text className="item2">FOUR</text>
        <text className="item2">FIVE</text>
        <text className="item2">SIX</text>
        <text className="item2">SEVEN</text>
        <text className="item2">EIGHT</text>
        <text className="item2">NINE</text>
        <text className="item2">TEN</text>
      </view>
    </>
  );
};

root.render(<RowGap />);

```



## Values

### `<length>`

[`<length>`](/api/css/data-type/length.md) is the width of the gutter separating the rows.

### `<percentage>`

[`<percentage>`](/api/css/data-type/percentage.md) values are relative to the dimension of the element.

## Formal syntax

```
row-gap = <length-percentage [0,∞]>

<length-percentage> = <length> | <percentage>
```

## Syntax

```css
/* <length> values */
row-gap: 20px;
row-gap: 1em;

/* <percentage> value */
row-gap: 10%;

/* calc() values */
row-gap: calc(10% + 20px);
```

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>0</code>
  </>
}
  appliesTo={<>flex containers, grid containers</>}
  inherited="no"
  percentages={<>refer to vertical dimension of its own content area</>}
/>

## Difference with the web

[mdn: row-gap](https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap)

1. `normal` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.row-gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/row-gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/row-gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |

**Description:** <code>row-gap</code>


## FAQ



---
url: /api/css/properties/text-align.md
---

<APISummary />

## Introduction

The `text-align` CSS property sets the horizontal alignment of the inline-level content inside a block element.

## Examples

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-normal.jpeg" style={{ width: '45%', marginRight: '10px', marginBottom: '10px' }} />

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-ltr.jpeg" style={{ width: '45%', marginBottom: '10px' }} />

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-rtl.jpeg" style={{ width: '45%', marginRight: '10px' }} />

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-lynx-rtl.jpeg" style={{ width: '45%' }} />

## Syntax

```css
/* Keyword values */
text-align: start;
text-align: end;
text-align: left;
text-align: right;
text-align: center;
```

### Values

- `left`
  The inline contents are aligned to the left edge of the line box.

- `right`
  The inline contents are aligned to the right edge of the line box.

- `center`
  The inline contents are centered within the line box.

- `start`
  The same as left if direction is left-to-right and right if direction is right-to-left.
  **When `direction` is `normal`, `start` is the nature direction of text。**

- `end`
  The same as right if direction is left-to-right and left if direction is right-to-left.

## Formal definition


<PropertyDefinition initialValue={<>start</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal syntax

```
left | right | center | start | end
```

## Difference with web

- Not support `justify-all` and `justify`.

- Not support `match-parent`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-align`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-decoration.md
---

<APISummary />

## Introduction

The `text-decoration` shorthand CSS property sets the appearance of decorative lines on text.

## Examples

**This is an example below:  css-api**

**Entry:** `src/text-decoration`
**Bundle:** `dist/text-decoration.lynx.bundle`

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

const TextDecoration = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const headerStyle = {
    backgroundColor: "#ccc",
    marginTop: "10px",
  };

  const noneStyle = {
    textDecoration: "none",
  };

  const underlineStyle = {
    textDecoration: "underline",
  };

  const lineThroughStyle = {
    textDecoration: "line-through",
  };

  const redSolidStyle = {
    textDecoration: "underline line-through red solid",
  };

  const greenDottedStyle = {
    textDecoration: "underline line-through green dotted",
  };

  const blueDashedStyle = {
    textDecoration: "underline line-through blue dashed",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text style={headerStyle}>text-decoration</text>
          <text style={noneStyle}>None</text>
          <text style={underlineStyle}>Underline</text>
          <text style={lineThroughStyle}>Line Through</text>
          <text style={redSolidStyle}>Red Solid Line</text>
          <text style={greenDottedStyle}>Green Dotted Line</text>
          <text style={blueDashedStyle}>Blue Dashed Line</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<TextDecoration />);

```



## Syntax

```css
text-decoration: underline;
text-decoration: line-through red;
text-decoration: none;
```

### Values

#### **text-decoration-line**

The `text-decoration-line` CSS property sets the kind of decoration that is used on text in an element.

- `none` <br />
  **Default value**. Produces no text decoration.

- `underline`
  Each line of text has a decorative line beneath it.

- `line-through`
  Each line of text has a decorative line going through its middle.

#### **text-decoration-color**

The `text-decoration-color` CSS property sets the color of decorations.

- [`<color>`](/api/css/data-type/color.md)

#### **text-decoration-style**

The `text-decoration-style` CSS property sets the style of the lines specified by `text-decoration-line`.

- `solid`
  Draws a single line.

- `double`
  Draws a double line.

- `dotted`
  Draws a dotted line.

- `dashed`
  Draws a dashed line.

- `wavy`
  Draws a wavy line.

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Differences from Web

- Not support [`text-decoration-thickness`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-decoration-thickness)
- Not support multiple decoration lines.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-align`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-indent.md
---

<APISummary />

## Introduction

The text-indent attribute can define the indentation before the first line of text content of a text.

## Examples

**This is an example below:  css-api**

**Entry:** `src/text-indent`
**Bundle:** `dist/text-indent.lynx.bundle`

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

const TextIndent = () => {
  const textStyle = {
    textIndent: "10px",
  };

  return (
    <text style={textStyle}>
      hello world, Now we can use text-indent in the text node
    </text>
  );
};

root.render(<TextIndent />);

```



## Syntax

```css
/* <length> values */
text-indent: 40px;

/* <percentage> value
   relative to the containing block width */
text-indent: 15%;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Length value, defaults to 0

- [`<percentage>`](/api/css/data-type/percentage.md)
  Percentage relative to the `text` width

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
<length> | <percentage>
```

## Difference with web

When writing **percentage**, you need to specify the width of the text element, otherwise, it will not take effect

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-indent`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-indent](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-indent)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-overflow.md
---

<APISummary />

## Introduction

The `text-overflow` CSS property sets how hidden overflow content is signaled to users.

## Examples

**This is an example below:  css-api**

**Entry:** `src/text-overflow`
**Bundle:** `dist/text-overflow.lynx.bundle`

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

const TextOverflow = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const sampleText = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

  return (
    <view style={containerStyle}>
      <text className="title">text-overflow: clip</text>
      <text className="item clip" text-maxline="2">
        {sampleText}
      </text>

      <text className="title">text-overflow: ellipsis</text>
      <text className="item overflow" text-maxline="2">
        {sampleText}
      </text>
    </view>
  );
};

root.render(<TextOverflow />);

```



## Syntax

```css
text-overflow: clip;
text-overflow: ellipsis;
```

### Values

- `clip` <br />
  **Default Value**。This keyword value will truncate the text at the limit of the content area.

- `ellipsis` <br />
  This keyword value will display an ellipsis (`…`, `U+2026 HORIZONTAL ELLIPSIS`) to represent clipped text.

## Formal definition


<PropertyDefinition initialValue={<>clip</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
clip | ellipsis
```

## Difference between web

- Not support `fade` 。

- Not support `<string>` with custom clip text.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-overflow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-overflow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-overflow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-shadow.md
---

<APISummary />

## Introduction

The `text-shadow` CSS property adds shadows to text.

## Examples

**This is an example below:  css-api**

**Entry:** `src/text-shadow`
**Bundle:** `dist/text-shadow.lynx.bundle`

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

const TextShadow = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const headerStyle = {
    backgroundColor: "#ccc",
    marginTop: "10px",
  };

  const noneStyle = {
    textShadow: "none" as const,
  };

  const singleStyle = {
    textShadow: "1px 1px 2px #558abb" as const,
  };

  const multiStyle = {
    textShadow: "1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue" as const,
  };

  const rgbaStyle = {
    textShadow: "0 .005px .01rem rgba(70, 70, 70, .3)" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text style={headerStyle}>text-shadow</text>
          <text style={noneStyle}>text-shadow: none;</text>
          <text style={singleStyle}>text-shadow: 1px 1px 2px #558abb;</text>
          <text style={multiStyle}>text-shadow: 1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue;</text>
          <text style={rgbaStyle}>text-shadow: 0 .005px .01rem rgba(70, 70, 70, .3);</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<TextShadow />);

```



## Syntax

```css
/* offset-x | offset-y | blur-radius | color */
text-shadow: 1px 1px 2px black;

/* color | offset-x | offset-y | blur-radius */
text-shadow: #fc0 1px 0 10px;

/* offset-x | offset-y | color */
text-shadow: 5px 5px #558abb;

/* color | offset-x | offset-y */
text-shadow: white 2px 5px;

/* offset-x | offset-y
/* Use defaults for color and blur-radius */
text-shadow: 5px 10px;
```

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>text</>} inherited="yes" animatable="no" />

## Formal Syntax

```
none | [ <length>{3} <color> ]
```

## Differences from Web

- Only support one shadow layer.

- For now both `offset-x`,`offset-y`,`blur-radius` and `color` are mandatory. And `color` must be the last value.

## Notes

- In some old version Android platform, `text-shadow` may not be rendered when `blur-radius` is 0.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-shadow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-shadow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-shadow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-stroke-color.md
---

<APISummary />

## Introduction

`text-stroke-color` specifies the stroke color of characters of text.

## Example

**This is an example below:  css-api**

**Entry:** `src/text-stroke-color`
**Bundle:** `dist/text-stroke-color.lynx.bundle`

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

const TextStokeColor = () => {
  const textStyleRed = {
    textStrokeWidth: "1px",
    textStrokeColor: "#ff0000",
  };
  const textStyleGreen = {
    textStrokeWidth: "1px",
    textStrokeColor: "green",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyleRed}>The stroke of this text is red</text>
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyleGreen}>The stroke of this text is green</text>
    </scroll-view>
  );
};

root.render(<TextStokeColor />);

```



## Syntax

```css
text-stroke-color: red;
text-stroke-color: #e08ab4;
text-stroke-color: rgb(200, 100, 0);
```

### Values

- [`<color>`](/api/css/properties/color.md)<br />
  The color of the stroke.

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
text-stroke-color = <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-stroke-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-stroke-width.md
---

<APISummary />

## Introduction

The `text-stroke-width` property specifies the width of the text stroke.

## Examples

**This is an example below:  css-api**

**Entry:** `src/text-stroke-width`
**Bundle:** `dist/text-stroke-width.lynx.bundle`

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

const TextStokeColor = () => {
  const textStyle1 = {
    textStrokeWidth: "1px",
    textStrokeColor: "red",
  } as const;
  const textStyle2 = {
    textStrokeWidth: "0.5px",
    textStrokeColor: "red",
  } as const;

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyle1}>The stroke width of this text is 1px</text>
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyle2}>The stroke width of this text is 0.5px</text>
    </scroll-view>
  );
};

root.render(<TextStokeColor />);

```



## Syntax

```css
text-stroke-width: 2px;
text-stroke-width: 0.1em;
text-stroke-width: 5pt;
```

### Values

- [`<length>`](/api/css/data-type/length.md)<br />
  The width of the stroke.

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
text-stroke-width = <length[0,∞]>
```

## Differences from Web

- Does not support setting attribute values such as `thin`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-stroke-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-stroke.md
---

<APISummary />

## Introduction

The `text-stroke` CSS property specifies the width and color of strokes for text characters.

## Examples

**This is an example below:  css-api**

**Entry:** `src/text-stroke`
**Bundle:** `dist/text-stroke.lynx.bundle`

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

const TextStroke = () => {
  const textStyle = {
    textStroke: "1px red",
  } as const;

  return (
    // @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types`
    <text style={textStyle}>
      The stroke of this text is red
    </text>
  );
};

root.render(<TextStroke />);

```



## Syntax

```css
text-stroke: 4px green;
```

### Values

- none <br />
  **Default value**

- [`<length>`](/api/css/data-type/length.md) <br />
  Set the width of the stroke

- [`<color>`](/api/css/properties/color.md) <br />
  Set the color of the stroke

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
text-stroke = none | <length [0,∞]> || <color>
```

## Differences from Web

- Does not support setting attribute values such as `thin` for stroke width.

## Notes

- Some fonts may have overlapping strokes.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-stroke`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke](https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/top.md
---

<APISummary />

## Introduction

The `top` CSS property participates in specifying the vertical position. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `top` depends on how the element is positioned (i.e., the value of the position property):

- When position is set to `absolute` or `fixed`, the `top` property specifies the distance between the element's outer margin of top edge and the inner border of the top edge of its containing block.

- When `position` is set to `relative`, the `top` property specifies the distance the element's top edge is moved below its normal position.

When both `top` and `bottom` are specified, position is set to `absolute` or `fixed`, and `height` is unspecified (either `auto` or 100%) both the `top` and `bottom` distances are respected. In all other situations, if `height` is constrained in any way or `position` is set to `relative`, the top property takes precedence and the `bottom` property is ignored.

## Examples

**This is an example below:  css-api**

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

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

const Top = () => {
  const containerStyle = {
    width: "210px",
    height: "210px",
    border: "5px",
    borderColor: "black",
  };

  const firstBoxStyle = {
    position: "absolute" as const,
    top: "80px",
    width: "50px",
    height: "50px",
    backgroundColor: "red",
  };

  const secondBoxStyle = {
    position: "fixed" as const,
    top: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "green",
  };

  const thirdBoxStyle = {
    position: "relative" as const,
    top: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "yellow",
  };

  const fourthBoxStyle = {
    width: "50px",
    height: "50px",
    backgroundColor: "blue",
  };

  return (
    <view style={containerStyle}>
      <view style={firstBoxStyle}></view>
      <view style={secondBoxStyle}></view>
      <view style={thirdBoxStyle}></view>
      <view style={fourthBoxStyle}></view>
    </view>
  );
};

root.render(<Top />);

```



## Syntax

```css
/* <length> values */
top: 3px;
top: 2rpx;
top: 2.4em;
top: 3rem;

top: 10%;

/* Keyword value */
top: auto;

/* calc */
top: calc(1px + 1px);
```

### Values

#### `auto`

**Default value**.

#### `<length>`

A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

- for absolutely positioned elements, the distance to the top edge of the containing block.

- for relatively positioned elements, the distance that the element is moved below its normal position.

#### `<percentage>`

Defines the height as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s height.

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Difference with the web

[mdn: top](https://developer.mozilla.org/en-US/docs/Web/CSS/bottom)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** participates in setting the vertical position of a positioned element. It has no effect on non-positioned elements.


## FAQ



---
url: /api/css/properties/transform-origin.md
---

<APISummary />

## Introduction

The transform-origin CSS property sets the origin for an element's transformations.

## Examples

**This is an example below:  css-api**

**Entry:** `src/transform-origin`
**Bundle:** `dist/transform-origin.lynx.bundle`

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

const TransformOrigin = () => {
  const emptyBoxStyle = {
    position: "absolute",
    width: "100px",
    height: "100px",
    border: "1px solid black",
  } as const;

  const redBoxStyle = {
    position: "absolute",
    width: "100px",
    height: "100px",
    backgroundColor: "red",
    transform: "rotate(45rad)",
  } as const;

  const greenBoxStyle = {
    position: "absolute",
    width: "100px",
    height: "100px",
    backgroundColor: "green",
    transformOrigin: "50% top",
    transform: "rotate(45rad)",
  } as const;

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="intro">
        <view style={redBoxStyle} />
        <view style={emptyBoxStyle} />
      </view>
      <view className="intro">
        <view style={greenBoxStyle} />
        <view style={emptyBoxStyle} />
      </view>
    </scroll-view>
  );
};

root.render(<TransformOrigin />);

```



## Syntax

```scss
/* x-offset | default */
transform-origin: 2px;
transform-origin: bottom;

/* x-offset | y-offset */
transform-origin: 3cm 2px;

/* x-offset-keyword | y-offset */
transform-origin: left 2px;

/* x-offset-keyword | y-offset-keyword */
transform-origin: right top;

/* x-offset | y-offset */
transform-origin: 2px 30%;

/* x-offset-keyword | y-offset */
transform-origin: left 5px;

/* x-offset-keyword | y-offset-keyword */
transform-origin: right bottom;
```

### Values

The value of the `transform-origin` can be one or two. **The first value represents `x-offset`**, **the second value represents `y-offset`**, **separated by a space**.

#### x-offset

The value of `x-offset` can be length `<length>`, percentage `<x-percentage>`, keyword `<x-offset-keyword>`

- **length**
  Length value, the unit is px,rem,rpx, etc.

- **x-percentage**
  Percentage relative to parent View**Width**.

- **x-offset-keyword**

| Keyword | Value |
| ------- | ----- |
| left    | 0%    |
| center  | 50%   |
| right   | 100%  |

#### y-offset

The value of `y-offset` can be length `<length>`, percentage `<y-percentage>`, keyword `<y-offset-keyword>`

- **length**
  Length value, the unit is px,rem,rpx, etc.

- **y-percentage**
  Percentage relative to parent View**Height**.

- **y-offset-keyword**

| Keyword | Value |
| ------- | ----- |
| top     | 0%    |
| center  | 50%   |
| bottom  | 100%  |

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Difference from W3C

- Transform-origin is not supported for z-axis

## Note

- The first value of transform-origin always means `x-offset`, the second value always means `y-offset`, please do not write inverse.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transform-origin`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform-origin](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform-origin)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transform.md
---

<APISummary />

## Introduction

The transform CSS property lets you rotate, scale, skew, or translate an element.

## Examples

**This is an example below:  css-api**

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

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

const Transform = () => {
  const containerStyle = {
    flexDirection: "column" as const,
    alignItems: "center",
    padding: "20px",
    backgroundColor: "#f5f5f5",
  } as const;

  const boxBaseStyle = {
    width: "120px",
    height: "120px",
    backgroundColor: "#2196F3",
    margin: "25px",
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
  } as const;

  const textStyle = {
    color: "white",
    fontSize: "16px",
    textAlign: "center" as const,
  } as const;

  const rotateStyle = {
    ...boxBaseStyle,
    transform: "rotate(45deg)",
    backgroundColor: "#4CAF50",
  } as const;

  const scaleStyle = {
    ...boxBaseStyle,
    transform: "scale(1.2)",
    backgroundColor: "#FF9800",
  } as const;

  const translateStyle = {
    ...boxBaseStyle,
    transform: "translate(50px, 0)",
    backgroundColor: "#9C27B0",
  } as const;

  const multipleStyle = {
    ...boxBaseStyle,
    transform: "rotate(45deg) scale(0.8) translate(50px, 0)",
    backgroundColor: "#E91E63",
  } as const;

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={containerStyle}>
        <view style={rotateStyle}>
          <text style={textStyle}>Rotate 45°</text>
        </view>

        <view style={scaleStyle}>
          <text style={textStyle}>Scale 1.2x</text>
        </view>

        <view style={translateStyle}>
          <text style={textStyle}>Move Right 50px</text>
        </view>

        <view style={multipleStyle}>
          <text style={textStyle}>Combined Effects</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Transform />);

```



## Syntax

```scss
/* Function values */
transform: rotate(0.5turn);
transform: rotateX(10deg);
transform: rotateY(10deg);
transform: translate(12px, 50%);
transform: translate3d(12px, 50%, 3em);
transform: translateX(2em);
transform: translateY(3px);
transform: translateZ(2px);
transform: scale(2, 0.5);
transform: scaleX(2);
transform: scaleY(0.5);

// equal to transform: translate(50px, 100px);
transform: matrix(1, 0, 0, 1, 50, 100);
// equal to transform: translateX(100px);
transform: matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 100, 0, 0, 1);

/* Multiple function values */
transform: translateX(10px) rotate(10deg) translateY(5px);
transform: translate3d(10px, 0, 20px) rotateY(3deg);
```

The value of the `transform` can be one or more `<function>`, which are separated by spaces. For details, see [function standard syntax](#function-standard-syntax)

### function standard syntax

- **translate**

```
translate( <length> | <percentage> , <length> | <percentage>? )
```

- **translateX**

```
translateX( <length> | <percentage> )
```

- **translateY**

```
translateY( <length> | <percentage> )
```

- **translateZ**

```
translateZ( <length> )
```

:::info
When using translateZ, it is recommended to set `flatten={false}` on the parent node of the node, otherwise it may cause the `overflow:hidden` of the parent node to fail on Android.
At the same time, if translateZ does not take effect on Android, you can try to set other sibling nodes of the same parent node to `transform: translateZ(0)`.
:::

- **translate3d**

```
translate3d( <length> | <percentage> , <length> | <percentage> , <length> )
```

- **rotate**

```
rotate( [ <angle> | <zero> ] )
```

- **rotateZ**

```
rotateZ( [ <angle> | <zero> ] )
```

- **rotateX**

```
rotateX( [ <angle> | <zero> ] )
```

- **rotateY**

```
rotateY( [ <angle> | <zero> ] )
```

- **scale**

```
scale( <number> , <number>? )
```

- **scaleX**

```
scaleX( <number> )
```

- **scaleY**

```
scaleY( <number> )
```

- **skew**

```
skew( [ <angle> | <zero> ], [ <angle> | <zero> ] )
```

- **skewX**

```
skewX( [ <angle> | <zero> ] )
```

- **skewY**

```
skewY( [ <angle> | <zero> ] )
```

- **matrix**

```
matrix(a, b, c, d, tx, ty)
```

- **matrix3d**

```
matrix3d(a1, b1, c1, d1, a2, b2, c2, d2, a3, b3, c3, d3, a4, b4, c4, d4);
```

::: info

- `matrix(a, b, c, d, tx, ty)` is shorthand for `matrix3d(a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, tx, ty, 0, 1)`.

- The `matrix3d()` function is specified with 16 arguments. These parameters are described in column-dominated order.

  - `a1`, `b1`, `c1`, `d1`
    define the first vector and are responsible for the X-axis scaling, rotation, and shear transformations;
  - `a2`, `b2`, `c2`, `d2`
    define the second vector and are responsible for the Y-axis scaling, rotation, and shear transformations;
  - `a3`, `b3`, `c3`, `d3`
    define the third vector and are responsible for the Z-axis scaling, rotation, and shear transformations;
  - `a4`, `b4`, `c4`, `d4`
    define the third vector, `a4`, `b4` and `c4` realize the translation transformation of x, y and z axes, and `d4` is generally set to 1, which is a value to keep the calculated weight stable.

:::

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Note

:::info

- If you want 3D effect when transform rotateX and rotateY rotate, you need to cooperate with [perspective property](/api/css/properties/perspective.md).

- On iOS, if there is jaggedness in rotate, anti-aliasing can be turned on by adding the `allow-edge-antialiasing` attribute to the node.

```jsx
<view allow-edge-antialiasing={true}></view>
```

- `iOS` will penetrate other sibling nodes in the same layer when rendering `rotateX/rotateY`. If you do not want this penetration effect, wrap the node with a Wrapper View so that it is not in the same layer as its sibling nodes. Since an empty Wrapper View will be optimized and deleted by layout only, without generating an actual node, please add a default `transform` property value to the Wrapper View (e.g. `transform: translate(0,0)`) to prevent it from being layout only.

:::

:::info

- The transform property is order-dependent, and the order of translate, rotate, and scale will affect the final rendering effect.

- The table below shows whether Lynx considers the order of transform in various scenarios:

| Scenario                    | Consideration of Transform Order |
| --------------------------- | -------------------------------- |
| Static transform in Android | Yes                              |
| Static transform in iOS     | Yes                              |
| Transform in Android        | Yes                              |
| Transform in iOS            | Yes                              |

- _What is a static transform: It refers to the transform property that is rendered directly without animation in CSS._

:::

## Difference from W3C

- not support rotate3d, scale3d

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transform`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-delay.md
---

# transition-delay

<APISummary />

## Introduction

The transition-delay CSS property specifies the duration to wait before starting a property's transition effect when its value changes.

## Examples

**This is an example below:  css-api**

**Entry:** `src/transition-delay`
**Bundle:** `dist/transition-delay.lynx.bundle`

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

const TransitionDelay = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
        }}
      >
        <text>No delay animation</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDelay: "1s" as const,
        }}
      >
        <text>1s delay animation</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDelay: "2s" as const,
        }}
      >
        <text>2s delay animation</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDelay: "3s" as const,
        }}
      >
        <text>3s delay animation</text>
      </view>
    </scroll-view>
  );
};

root.render(<TransitionDelay />);

```



## Syntax

```css
transition-delay: 2s;
transition-delay: 300ms;
```

### Values

- [`<time>`](/api/css/data-type/time.md)

- Default Value
  **0s**

## Formal definition


<PropertyDefinition initialValue={<>0</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
transition-delay:`<time>`;
```

## More

- [transition-property](/api/css/properties/transition-property.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Note

:::info

- `duration` and `delay` require **units**, and it is strongly recommended to bring units.

:::

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-delay`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-delay](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-delay)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-duration.md
---

# transition-duration

<APISummary />

## Introduction

The transition-duration CSS property sets the length of time a transition animation should take to complete. By default, the value is 0s, meaning that no animation will occur.

## Examples

**This is an example below:  css-api**

**Entry:** `src/transition-duration`
**Bundle:** `dist/transition-duration.lynx.bundle`

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

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "0.3s",
        }}
      >
        <text>0.3s duration transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "1s",
        }}
      >
        <text>1s duration transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "2s",
        }}
      >
        <text>2s duration transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "3s",
        }}
      >
        <text>3s duration transition</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
transition-duration: 2s;
transition-duration: 300ms;
```

### Values

- [`<time>`](/api/css/data-type/time.md)

- Default Value
  **0s**

## Formal syntax

```css
transition-duration: <time>;
```

## More

- [transition-property](/api/css/properties/transition-property.md)
- [transition-delay](/api/css/properties/transition-delay.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Note

:::info

- `duration` and `delay` require **units**, and it is strongly recommended to bring units.

:::

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-duration`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-duration](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-duration)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-property.md
---

# transition-property

<APISummary />

## Introduction

The transition-property CSS property sets the CSS properties to which a transition effect should be applied.

## Examples

**This is an example below:  css-api**

**Entry:** `src/transition-property`
**Bundle:** `dist/transition-property.lynx.bundle`

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

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view className="base opacityTransition" style={{ opacity: baseStyle.opacity }}>
        <text>Opacity animation</text>
      </view>
      <view className="base widthTransition" style={{ width: baseStyle.width }}>
        <text>Width animation</text>
      </view>
      <view className="base heightTransition" style={{ height: baseStyle.height }}>
        <text>Height animation</text>
      </view>
      <view className="base bgColorTransition" style={{ backgroundColor: baseStyle.backgroundColor }}>
        <text>Background color animation</text>
      </view>
      <view className="base transformTransition" style={{ transform: baseStyle.transform }}>
        <text>Transform animation</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
/* Keyword values */
transition-property: none;
transition-property: all;

/* <custom-ident> values */
transition-property: test_05;
transition-property: -specific;
transition-property: sliding-vertically;

/* Multiple values */
transition-property: test1, animation4;
transition-property: all, height, color;
```

### Values

- left
- right
- top
- bottom
- width
- height
- opacity
- background-color
- color
- transform
- transform-origin
- max-width
- min-width
- max-height
- min-height
- padding-left
- padding-right
- padding-top
- padding-bottom
- margin-left
- margin-right
- margin-top
- margin-bottom
- border-left-width
- border-right-width
- border-top-width
- border-bottom-width
- border-left-color
- border-right-color
- border-top-color
- border-bottom-color
- flex-basis
- flex-grow
- filter

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
transition-property =
  none                           |
  <single-transition-property>#

<single-transition-property> =
  all             |
  <custom-ident>
```

## More

- [transition-delay](/api/css/properties/transition-delay.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-property`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-property](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-property)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-timing-function.md
---

# transition-timing-function

<APISummary />

## Introduction

The transition-timing-function CSS property sets how intermediate values are calculated for CSS properties being affected by a transition effect.

## Examples

**This is an example below:  css-api**

**Entry:** `src/transition-timing-function`
**Bundle:** `dist/transition-timing-function.lynx.bundle`

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

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "linear",
        }}
      >
        <text>linear transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease",
        }}
      >
        <text>ease transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease-in",
        }}
      >
        <text>ease-in transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease-out",
        }}
      >
        <text>ease-out transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease-in-out",
        }}
      >
        <text>ease-in-out transition</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
transition-timing-function: ease;
transition-timing-function: ease-in;
transition-timing-function: ease-out;
transition-timing-function: ease-in-out;
transition-timing-function: linear;
transition-timing-function: step-start;
transition-timing-function: step-end;

transition-timing-function: cubic-bezier(0.1, 0.7, 1, 0.1);
```

### Values

- `linear`

- `ease`

- `ease-in`

- `ease-out`

- `ease-in-out`

- `square-bezier()`

- `cubic-bezier()`

Default : **linear**

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
transition-timing-function:linear|ease|ease-in|ease-out|ease-in-out|square-bezier()|cubic-bezier();
```

## More

- [transition-delay](/api/css/properties/transition-delay.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-timing-function`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-timing-function](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-timing-function)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition.md
---

# transition

<APISummary />

## Introduction

The transition CSS property is a shorthand property for `transition-property`, `transition-duration`, `transition-timing-function`, and `transition-delay`.

## Example

**This is an example below:  css-api**

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

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

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view className="base opacityTransition" style={{ opacity: baseStyle.opacity }}>
        <text>opacity animation</text>
      </view>
      <view className="base widthTransition" style={{ width: baseStyle.width }}>
        <text>width animation</text>
      </view>
      <view className="base heightTransition" style={{ height: baseStyle.height }}>
        <text>height animation</text>
      </view>
      <view className="base bgColorTransition" style={{ backgroundColor: baseStyle.backgroundColor }}>
        <text>background-color animation</text>
      </view>
      <view className="base transformTransition" style={{ transform: baseStyle.transform }}>
        <text>transform animation</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
/* Apply to 1 property */
/* property name | duration */
transition: background-color 4s;

/* property name | duration | delay */
transition: opacity 4s 1s;

/* property name | duration | easing function */
transition: background-color 4s ease-in-out;

/* property name | duration | easing function | delay */
transition: background-color 4s ease-in-out 1s;

/* Apply to 2 properties */
transition:
  background-color 4s,
  opacity 4s;

/* Apply to all changed properties */
transition: all 0.5s ease-out;

/* Clear all transition animation.*/
transition: none;
```

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```css
transition: <transition-property> || <transition-duration> ||
  <transition-timing-function> || <transition-delay>;
```

## Transition Event

- [Transition Event](/api/lynx-api/event/animation-event.md)

## More

- [transition-property](/api/css/properties/transition-property.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition-delay](/api/css/properties/transition-delay.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/vertical-align.md
---

<APISummary />

## Introduction

The vertical-align property sets vertical alignment of inline element.

## Examples

**This is an example below:  css-api**

**Entry:** `src/vertical-align`
**Bundle:** `dist/vertical-align.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";
import playImage from "../../resource/play.jpeg";

const VerticalAlign = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const titleStyle = {
    backgroundColor: "white",
  };

  const orangeContainerStyle = {
    lineHeight: "100px",
    backgroundColor: "orange",
  };

  const tomatoContainerStyle = {
    lineHeight: "100px",
    backgroundColor: "tomato",
  };

  const titleTextStyle = {
    fontSize: "25px",
  };

  const imageStyle = (align: string) => ({
    width: "20px",
    height: "20px",
    verticalAlign: align,
  });

  const textStyle = (align: string) => ({
    verticalAlign: align,
  });

  const viewStyle = (align: string) => ({
    width: "20px",
    height: "20px",
    backgroundColor: "yellow",
    verticalAlign: align,
  });

  return (
    <view className="intro" style={containerStyle} lynx-test-tag="container">
      <text style={titleStyle}>
        set vertical-align: middle,center,top,bottom,text-top,text-bottom,super,baseline,sub
      </text>
      <text style={orangeContainerStyle}>
        <text style={titleTextStyle}>inline-image:</text>

        <image src={playImage} style={imageStyle("middle")}></image>
        <image src={playImage} style={imageStyle("center")}></image>
        <image src={playImage} style={imageStyle("top")}></image>
        <image src={playImage} style={imageStyle("bottom")}></image>
        <image src={playImage} style={imageStyle("text-top")}></image>
        <image src={playImage} style={imageStyle("text-bottom")}></image>
        <image src={playImage} style={imageStyle("super")}></image>
        <image src={playImage} style={imageStyle("baseline")}></image>
        <image src={playImage} style={imageStyle("sub")}></image>
      </text>
      <text style={tomatoContainerStyle}>
        <text style={titleTextStyle}>inline-text:</text>
        <text style={textStyle("middle")}>xx</text>
        <text style={textStyle("center")}>xx</text>
        <text style={textStyle("top")}>xx</text>
        <text style={textStyle("bottom")}>xx</text>
        <text style={textStyle("text-top")}>xx</text>
        <text style={textStyle("text-bottom")}>xx</text>
        <text style={textStyle("super")}>xx</text>
        <text style={textStyle("baseline")}>xx</text>
        <text style={textStyle("sub")}>xx</text>
      </text>
      <text style={orangeContainerStyle}>
        <text style={titleTextStyle}>inline-view</text>
        <view style={viewStyle("middle")}></view>
        <view style={viewStyle("center")}></view>
        <view style={viewStyle("top")}></view>
        <view style={viewStyle("bottom")}></view>
        <view style={viewStyle("text-top")}></view>
        <view style={viewStyle("text-bottom")}></view>
        <view style={viewStyle("super")}></view>
        <view style={viewStyle("baseline")}></view>
        <view style={viewStyle("sub")}></view>
      </text>
    </view>
  );
};

root.render(<VerticalAlign />);

```



## Syntax

```css
vertical-align: 10px;
vertical-align: 50%;
vertical-align: baseline;
vertical-align: middle;
vertical-align: center;
vertical-align: top;
vertical-align: bottom;
vertical-align: text-top;
vertical-align: text-bottom;
vertical-align: super;
vertical-align: sub;
```

### Values

- `<length>`
  support `length` in Lynx,aligns the baseline of the element to the given length above the initial baseline,a negative value is allowed.

- `<percent>`
  Shift a percentage of the `line-height`,a negative value is allowed.

- `baseline`
  Aligns the baseline of element with the baseline of line.

- `middle`
  Get max x-height of all of text,aligns the middle of element with the position of half max x-height.

- `center`
  Aligns the middle of the element with the middle of line.

- `top`
  Aligns the top of the element with the top of line.

- `bottom`
  Aligns the bottom of the element with the bottom of line.

- `text-top`
  Get max ascent of all of text,aligns the top of element with the position of max ascent.

- `text-bottom`
  Get max descent of all of text,aligns the bottom of element with the position of max descent.

- `super`
  Upward shift 10% of the element's height.

- `sub`
  Downward shift 10% of the element's height.

- default value
  **baseline**

## Formal definition


<PropertyDefinition initialValue={<>baseline</>} appliesTo={<>inline-text、inline-image、inline-view</>} inherited="no" animatable="no" />

## Formal syntax

```
<length> | <percent> | baseline | middle | center | top | bottom | text-top | text-bottom | super | sub
```

## Difference with Web

- [mdn:vertical-align](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align)

## Notes

- When the'text 'element nests the'view', the default text baseline is aligned to the bottom of the'view ', and the 'vertical-align-baseline' needs to be explicitly set on the'view 'to ensure that the text baseline is aligned to the'view' text baseline.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.vertical-align`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/vertical-align](https://developer.mozilla.org/zh-CN/docs/Web/CSS/vertical-align)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.6 | - |
| iOS | 2.6 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.6 | - |
| Clay iOS | 2.6 | - |
| Clay macOS | 2.6 | - |
| Clay Windows | 2.6 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/visibility.md
---

<APISummary />

## Introduction

The visibility CSS property shows or hides an element without changing the layout of a document.

## Examples

**This is an example below:  css-api**

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

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

import image from "../../resource/lynx.png";

const Visibility = () => {
  const heightStyle = {
    height: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <image className="relative_image" src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image visible" src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image hidden" src={image}></image>
      </view>
    </scroll-view>
  );
};

root.render(<Visibility />);

```



## Syntax

```css
/* Keyword values */
visibility: visible;
visibility: hidden;
```

### Values

`visible`

The element box is visible.

`hidden`

The element box is invisible (not drawn), but still affects layout as normal. Looks like 'opacity: 0'.

## Formal definition


<PropertyDefinition initialValue={<>visible</>} appliesTo={<>all elements</>} inherited="no" animatable="yes" />

## Formal syntax

```
visibility =
  visible   |
  hidden
```

## Differences from Web

`collapse`、`inherit`、`initial`and`unset` are not supported.

When `visibility` is set to `hidden`, all subviews will be invisible, no matter what values their `visibility` are.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.visibility`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/visibility](https://developer.mozilla.org/zh-CN/docs/Web/CSS/visibility)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/white-space.md
---

<APISummary />

## Introduction

`white-space`CSS property sets how white space inside an element is handled.。

## Examples

**This is an example below:  css-api**

**Entry:** `src/white-space`
**Bundle:** `dist/white-space.lynx.bundle`

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

const WhiteSpace = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const normalTextStyle = {
    className: "item normal",
  };

  const nowrapTextStyle = {
    className: "item nowrap",
  };

  const sampleText =
    "But ere she from the church-door stepped She smiled and told us why: 'It was a wicked woman's curse,' Quoth she, 'and what care I?' She smiled, and smiled, and passed it off Ere from the door she stept—";

  return (
    <view style={containerStyle}>
      <text className="title">white-space: normal</text>
      <text className="item normal">
        {sampleText}
      </text>

      <text className="title">white-space: nowrap</text>
      <text className="item nowrap">
        {sampleText}
      </text>
    </view>
  );
};

root.render(<WhiteSpace />);

```



## Syntax

```css
white-space: normal;

white-space: nowrap;
```

### Values

- `normal`
  **Default**
  No additional processing is performed on the text.

- `nowrap`
  Suppresses line breaks (text wrapping) within the source.

## Formal definition


<PropertyDefinition initialValue={<>normal</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
normal | nowrap
```

## Difference with Web

- Only support `normal` and `nowrap`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.white-space`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/white-space](https://developer.mozilla.org/zh-CN/docs/Web/CSS/white-space)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/width.md
---

<APISummary />

## Introduction

The `width` CSS property specifies the width of an element. By default, the property defines the width of the border area. If [`box-sizing`](/api/css/properties/box-sizing.md) is set to `content-box`, however, it instead determines the width of the content area.

The [`min-width`](/api/css/properties/min-width.md) and [`max-width`](/api/css/properties/max-width.md) properties override `width`.

## Examples

**This is an example below:  css-api**

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

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

const Width = () => {
  const containerStyle = {
    display: "linear" as const,
    linearOrientation: "vertical" as const,
  };

  const borderBoxStyle = {
    width: "100px",
    border: "20px solid orange",
  };

  const contentBoxStyle = {
    width: "100px",
    border: "20px solid orange",
    boxSizing: "content-box" as const,
  };

  return (
    <view style={containerStyle}>
      <text style={borderBoxStyle}>
        border-box
      </text>
      <text style={contentBoxStyle}>
        content-box
      </text>
    </view>
  );
};

root.render(<Width />);

```



## Syntax

```css
/* <length> values */
width: 300px;
width: 25em;

/* <percentage> value */
width: 75%;

/* Keyword values */
width: max-content;
width: fit-content;
width: fit-content(20em);
width: auto;
```

### Values

- `auto`

  **Default value**. lynx will calculate and select a width for the specified element.

- `<length>`

  [`<length>`](/api/css/data-type/length.md) defines the width as a distance value.

- `<percentage>`

  Defines the width as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s width.

- `max-content`

  The intrinsic preferred width.

- `fit-content`

  [`fit-content`](/api/css/data-type/fit-content.md) uses the computed size with the available space replaced by the specified argument.

## Formal definition


<PropertyDefinition
  initialValue={
  <>
    <code>auto</code>
  </>
}
  appliesTo={<>all elements</>}
  inherited="no"
  animatable="yes"
  percentages={<>refer to the width of the containing block</>}
/>

## Formal syntax

## Difference with the web

- By default, the property defines the width of the border area, while Web is `content area`.
- `min-content` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/word-break.md
---

<APISummary />

## Introduction

Used to specify how to break lines within a word.

## Examples

**This is an example below:  css-api**

**Entry:** `src/word-break`
**Bundle:** `dist/word-break.lynx.bundle`

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

const WordBreak = () => {
  const normalBreakStyle = {
    overflow: "hidden",
    wordBreak: "normal",
  } as const;

  const breakAllStyle = {
    overflow: "hidden",
    wordBreak: "break-all",
  } as const;

  return (
    <view className="container">
      <text text-maxline="1" style={normalBreakStyle}>
        Hello, Lynx!Hello, Lynx!Hello, Lynx!
      </text>
      <text text-maxline="1" style={breakAllStyle}>
        Hello, Lynx!Hello, Lynx!Hello, Lynx!
      </text>
    </view>
  );
};

root.render(<WordBreak />);

```



## Syntax

```css
word-break: break-all;
word-break: normal;
```

### Values

- `normal`
  **Default value**. Use the default line break rule.

- `break-all`
  Lines can be interrupted in any character.

- `keep-all`
  Word breaks should not be used for Chinese/Japanese/Korean (CJK) text.

## Formal definition


<PropertyDefinition initialValue={<>normal</>} appliesTo={<>text</>} inherited="no" animatable="no" />

## Formal syntax

```
normal | break-all | keep-all
```

## Difference with Web

- [mdn:word-break](https://developer.mozilla.org/en-US/docs/Web/CSS/word-break)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.word-break`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/word-break](https://developer.mozilla.org/zh-CN/docs/Web/CSS/word-break)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/z-index.md
---

<APISummary />

## Introduction

The z-index CSS property sets the z-order of an element and its descendants or flex items. Overlapping elements with a larger z-index cover those with a smaller one.

:::info

If we want to generate [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context), you can add `z-index: 0` to an element. For example, make children follow the scroll by adding `z-index: 0` to the scroll-view

It is not recommended to use z-index in the direct children of list. This may affect the reuse of list. If you use z-index in the list item, the item should be a stacking context.

:::

## Examples

**This is an example below:  css-api**

**Entry:** `src/z-index`
**Bundle:** `dist/z-index.lynx.bundle`

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

const ZIndex = () => {
  const [indices, setIndices] = useState([2, 1, 0, -1, -2]);
  const [show, setShow] = useState(false);

  const containerStyle = {
    zIndex: 0,
    height: "280px",
  };

  const innerContainerStyle = {
    height: "100%",
  };

  const getBlockStyle = (index: number, color: string, top: string, left: string) => ({
    zIndex: indices[index],
    background: color,
    position: "absolute" as const,
    top,
    left,
  });

  const getTextStyle = (show: boolean) => ({
    top: show ? "0" : "80px",
  });

  const handleChange = () => {
    setIndices(show ? [2, 1, 0, -1, -2] : [-2, -1, 0, 1, 2]);
    setShow(!show);
  };

  return (
    <view className="main" bindtap={handleChange}>
      <view className="container" style={containerStyle}>
        <view className="container" style={innerContainerStyle}>
          <view className="block" style={getBlockStyle(0, "#2196F3", "10px", "10px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[0]}</text>
          </view>
          <view className="block" style={getBlockStyle(1, "#4CAF50", "50px", "50px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[1]}</text>
          </view>
          <view className="block" style={getBlockStyle(2, "#9C27B0", "90px", "90px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[2]}</text>
          </view>
          <view className="block" style={getBlockStyle(3, "#FF9800", "130px", "130px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[3]}</text>
          </view>
          <view className="block" style={getBlockStyle(4, "#E91E63", "170px", "170px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[4]}</text>
          </view>
        </view>
      </view>
    </view>
  );
};

root.render(<ZIndex />);

```



## Syntax

```css
z-index: 0;
z-index: 3;
z-index: 289;
z-index: -1;
```

### Values

- [`<number>`](/api/css/data-type/number.md)
  This integer is the stack level of the generated box in the current stacking context.

- Default value
  **auto**

## Formal definition


<PropertyDefinition initialValue={<>empty value</>} appliesTo={<>all elements</>} inherited="no" animatable="no" />

## Formal syntax

```
z-index = <integer>
```

## Difference between web

The default value of web is auto. Lynx determines whether it is a stacking context by setting z-index property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.z-index`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/z-index](https://developer.mozilla.org/zh-CN/docs/Web/CSS/z-index)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/selectors.md
---

# Selectors

CSS selectors specify which elements a CSS rule applies to. Pedantically speaking, CSS selectors is an umbrella term that includes Selectors, Combinators, Pseudo-elements, and Pseudo-classes.

## Selectors

### Type selector

The CSS type selector matches elements by node name. In other words, it selects all elements of the given type.

#### Syntax

```css
element { property declarations }
```

#### Example Usage

```css
/* To match all <input> elements */
input {
  ...
}

```

#### Using `page` to Select the Root Node

Unlike on the Web, in Lynx, the `page` element is used to select the root node instead of `body`.

### Class selector

The CSS class selector matches elements based on the contents of their class attribute.

#### Syntax

```css
.className { property declarations }
```

#### Example Usage

```css
/* All elements with class="index" */
.index{
  ...
}
```

### Multiple Class Selectors

To select elements using multiple class names, specify that an element must contain all these classes by concatenating the class names together.

#### Syntax

```css
.className1.className2 { property declarations }

element.className1.className2 { property declarations }
```

#### Example Usage

```css
/* To match any input elements with a class that contains both "a" and "b". */
input.a.b{
  ...
}

/* element */
<input className="a b" /> /* selected */
```

### ID selector

The CSS ID selector matches an element based on the value of the element's id attribute. In order for the element to be selected, its id attribute must match exactly the value given in the selector.

#### Syntax

```css
#idName {  property declarations }
```

### Universal selector

The CSS universal selector (\*) matches elements of any type.

#### Syntax

```css
* {  property declarations }
```

## Combinator

### Descendant Combinator

e descendant combinator — typically represented by a single space (" ") character — combines two selectors such that elements matched by the second selector are selected if they have an ancestor (parent, parent's parent, parent's parent's parent, etc.) element matching the first selector. Selectors that utilize a descendant combinator are called descendant selectors.

**Compared to the old selector, it no longer restricts the levels of matched elements to two levels.**

#### Syntax

```css
selector1 selector2 selector3 {
  property declarations
}
```

#### Example Usage

```css
/* Match all "b" elements that are descendants of the "a" list. */
view.a .b{
   ...
}

/* element */
<view className="a" >
 <text className="b">hello</text> /* selected */
</view>
```

### Child Combinator

The child combinator (`>`) is placed between two CSS selectors. It matches only those elements matched by the second selector that are the direct children of elements matched by the first.

#### Syntax

```css
element1 > element2 {
  property declarations
}
```

#### Example Usage

```css
/* Match all text elements that are direct children of "a" view */
view.a > text {
  ...
}

/* element */
<view className="a" >
  <text>hello</text> /*selected*/
</view>
```

### Subsequent-sibling Combinator

The subsequent-sibling combinator (`~`, a tilde) separates two selectors and matches all instances of the second element that follow the first element (not necessarily immediately) and share the same parent element.

#### Syntax

```css
former_element ~ target_element { property declarations }
```

#### Example Usage

```css
/* Match all sibling text elements following view. */
view ~ text {
  ...
}

/* element */
<view className="a" />
<text />  /* selected */
...
<text />  /* selected */
```

### Next-sibling Combinator

The next-sibling combinator (`+`) separates two selectors and matches the second element only if it immediately follows the first element, and both are children of the same parent element.

#### Syntax

```css
former_element + target_element { property declarations }
```

#### Example Usage

```css
/*  Match the text element that come immediately after a view */
view + text {
  ...
}

/* element */
<view className="a" />
<text />  /*selected*/
<text />  /*not selected*/
```

### Selector list

The CSS selector list (`,`) selects all the matching nodes. A selector list is a comma-separated list of selectors.

#### Syntax

```css
selector1,selector2 { property declarations }
```

#### Example Usage

```css
/* All matching elements are selected. */
 selector1, selector2 {
  ...
}

Equivalent to

selector1 {
  ...
}

selector2 {
  ...
}
```

## Pseudo

### Pseudo-class

A `:` pseudo-class is a type of selector used to select elements in a specific state.

Supports

- `:active`
- `:not()`
- `:root`

#### `:not()`

Used to match elements that do not meet the conditions. Usage aligns with [W3C :not()](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:not)

#### `:root` \{#root-selector}

Similar to the `page` selector used to match the root node. Usage aligns with [W3C :root](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:root)

#### `:active`

When a node is pressed, it gets activated and selected. Releasing the finger deactivates it. Usage aligns with [W3C :active](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:active)

#### Example Usage

```css
/* Elements that are not <view> and not <text> elements */
root :not(view):not(text) {
  font-weight: bold;
}

/* Elements that are not .crazy or .fancy
   Note that this syntax is not well supported yet. */
body :not(.crazy, .fancy) {
  font-family: sans-serif;
}
```

## Pseudo-element

Lynx doesn't have pseudo-element support yet.

## Troubleshooting

### `!important` is not supported as specificity

By the weight ratio of CSS selectors, the total specificity of CSS rules is calculated to determine the priority order of style rules. The basic calculation logic for CSS specificity is as follows:

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



---
url: /api/elements/built-in/frame-API.md
---

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



---
url: /api/elements/built-in/frame.md
---

# `<frame>`

<APISummary />

A page element similar to HTML's `<iframe>`, which can embed a Lynx page into the current page.

## Usage Guide

The following is an example of a main page loading an embedded page via the `<frame>` element.

- The main page passes `initData` and `globalProps` to the embedded page through the `data` and `globalProps` attributes.
- The main page listens for the embedded page loading status via the `bindload` event.

### Main Page

**This is an example below:  frame**

**Bundle:** `dist/frame.lynx.bundle`

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

import { type InitData, root, useState } from "@lynx-js/react";
import type { FrameLoadEvent, GlobalProps } from "@lynx-js/types";

const App = () => {
  const [bindLoadEvent, setBindLoadEvent] = useState({
    url: "",
    statusCode: 0,
    statusMessage: "",
  });
  const [initData, setInitData] = useState<InitData>({
    id: 123,
    name: "Alice",
    showDetail: true,
  });
  const [globalProps, setGlobalProps] = useState<GlobalProps>({
    message: "hello globalProps!",
    status: 42,
    loaded: true,
  });
  const handleLoad = (e: FrameLoadEvent) => {
    setBindLoadEvent(e.detail);
  };

  const frameUrl = `${process.env.ASSET_PREFIX}/in_frame.lynx.bundle`;
  return (
    <view>
      <text style={{ fontSize: "20px", color: "black", padding: "10px" }}>
        Below is the inline text example in frame page.
      </text>

      <frame
        style={{ width: "100%", height: "150px", border: "3px solid red" }}
        src={frameUrl}
        data={initData}
        bindload={handleLoad}
        global-props={globalProps}
      />
      <view
        style={{
          padding: "10px",
          width: "100%",
          height: "100px",
          border: "3px solid red",
        }}
        bindtap={() => setInitData({ ...initData, showDetail: !initData.showDetail })}
      >
        <text style={{ color: "black", fontSize: "20px" }}>
          {initData.showDetail ? "Hide Detail" : "Show Detail"}
        </text>
      </view>
      <text>load url: {bindLoadEvent.url}</text>
      <text>status code: {bindLoadEvent.statusCode}</text>
      <text>status message: {bindLoadEvent.statusMessage}</text>
    </view>
  );
};

root.render(<App />);

```



### Embedded Page

**This is an example below:  frame**

**Bundle:** `dist/frame.lynx.bundle`

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

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

export function App() {
  const initData = useInitData();
  const globalProps = lynx.__globalProps;

  return (
    <view>
      <text style={{ fontSize: "30px", color: "orange" }}>I'm in frame!</text>
      <view style={{ border: "3px solid blue" }}>
        <text>{initData.id}</text>
        <text>{initData.name}</text>
        <text>{initData.showDetail ? "true" : "false"}</text>
        <text>{globalProps.message}</text>
        <text>{globalProps.status}</text>
        <text>{globalProps.loaded ? "true" : "false"}</text>
      </view>
    </view>
  );
}

root.render(<App />);

```



:::tip
The `<frame>`
 element was introduced in <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




---
url: /api/elements/built-in/image-API.md
---

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.



---
url: /api/elements/built-in/image.md
---

# `<image>`

<APISummary />


Used to display different types of images, including web images, static resources, and locally stored images.

:::tip

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

:::

## Usage Guide

`<image>` is an [empty element](/guide/ui/elements-components.md#empty-elements) and no longer supports child nodes.

:::note

To display the image correctly, the non-empty [src](/api/elements/built-in/image.md#required-src) attribute must be set, and at least one of the following must be provided:

- A [width](/api/css/properties/width.md) and [height](/api/css/properties/width.md) greater than 0
- [auto-size](/api/elements/built-in/image.md#auto-size)

:::

The following examples show how the `<image>` element is used in different scenarios.

### Displaying images with different cropping/scaling modes

Supports controlling the image cropping/scaling mode using [mode](/api/elements/built-in/image.md#mode).

**This is an example below:  image**

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

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

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Adding borders, rounded corners, and backgrounds to the image

You can set the image's borders, rounded corners, and background colors using CSS styles.

**This is an example below:  image**

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

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

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Adding special drawing effects to the image

Supports special drawing effects like Gaussian blur.

**This is an example below:  image**

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

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

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Adapting to the original image aspect ratio

Use [auto-size](/api/elements/built-in/image.md#auto-size) to automatically adjust the `<image>` size to match the original image aspect ratio.

**This is an example below:  image**

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

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

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Listening to image load success/failure

You can bind [events](/api/elements/built-in/image.md#events) to listen for the image load state.

**This is an example below:  image**

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

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

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```




Used to display images

## Attributes

### `auto-size`

{' '}

<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


```
```



---
url: /api/elements/built-in/input-API.md
---

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

```
```



---
url: /api/elements/built-in/input.md
---

# `<input>`

<APISummary />


`<input>` is used to create interactive input controls that allow users to input and edit single-line text.

:::tip

This feature requires the client to add additional dependencies. Please refer to [More Elements](/guide/start/integrate-with-existing-apps.md) for the integration method.

:::

## Usage

### Basic

Below is a basic usage example of the `<input>` component:

**This is an example below:  input**

**Bundle:** `dist/autoHeight.lynx.bundle`

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

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

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "10px" }}>
      <view style={{ width: "100%", padding: "10px", backgroundColor: "#12345678", borderRadius: "10px" }}>
        <input
          style={{ width: "100%", color: "blue", fontSize: "30px" }}
          placeholder="search"
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>
      <scroll-view
        scroll-orientation="vertical"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "100%",
        }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <text style={{ fontSize: "20px", color: "gray", padding: "10px" }}>
              {`item-${index}${inputContent ? `-${inputContent}` : ""}`}
            </text>
          );
        })}
      </scroll-view>
    </view>
  );
};

root.render(<App />);

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

```



### Keyboard Avoidance

`<input>` doesn't automatically avoid keyboards, but you can adjust its position by listening to keyboard events and modifying its position accordingly:

**This is an example below:  input**

**Bundle:** `dist/autoHeight.lynx.bundle`

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

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

const App = () => {
  const [inputContent, setInputContent] = useState("");

  const setNativeProps = (itemId: string, props: Record<string, unknown>) => {
    lynx
      .createSelectorQuery()
      .select(`#${itemId}`)
      .setNativeProps(props)
      .exec();
  };

  const getItemRect = (
    itemId: string,
    success: (
      left: number,
      top: number,
      right: number,
      bottom: number,
      width: number,
      height: number,
    ) => void,
    fail?: (res: any) => void,
  ) => {
    const nodeRef = itemId === "root"
      ? lynx.createSelectorQuery().selectRoot()
      : lynx.createSelectorQuery().select(`#${itemId}`);

    nodeRef
      .invoke({
        method: "boundingClientRect",
        params: {
          relativeTo: "screen",
        },
        success: res => {
          success(
            /* eslint-disable @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access*/
            res.left,
            res.top,
            res.right,
            res.bottom,
            res.width,
            res.height,
            /* eslint-enable. no-safe-argument */
          );
        },
        fail: res => {
          fail?.(res);
        },
      })
      .exec();
  };

  const keyboardChanged = (keyboardHeightInPx: number) => {
    if (keyboardHeightInPx === 0) {
      setNativeProps("panel", {
        transform: `translateY(${0}px)`,
        transition: "transform 0.1s",
      });
    } else {
      setNativeProps("panel", {
        transform: `translateY(${-keyboardHeightInPx}px)`,
        transition: "transform 0.3s",
      });
    }
  };

  useLynxGlobalEventListener(
    "keyboardstatuschanged",
    (status: unknown, keyboardHeight: unknown) => {
      console.log(status);
      console.log(keyboardHeight);
      // @ts-ignore
      keyboardChanged(status === "on" ? keyboardHeight : 0);
    },
  );

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "10px" }}>
      <scroll-view
        scroll-orientation="vertical"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "100%",
        }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <text style={{ fontSize: "20px", color: "gray", padding: "10px" }}>
              {`item-${index}${inputContent ? `-${inputContent}` : ""}`}
            </text>
          );
        })}
      </scroll-view>
      <view
        id="panel"
        style={{
          width: "100%",
          padding: "10px",
          backgroundColor: "white",
          height: "100px",
          background: "lightgray",
          border: "1px solid black",
          position: "absolute",
          bottom: "0px",
        }}
      >
        {
          <input
            style={{ width: "100%", color: "blue", fontSize: "30px" }}
            placeholder="search"
            bindinput={(res: any) => {
              console.log(res.detail.value);
              setInputContent(res.detail.value);
            }}
          />
        }
      </view>
    </view>
  );
};

root.render(<App />);

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

```




## Attributes

### `android-fullscreen-mode`

{' '}

<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




---
url: /api/elements/built-in/list.md
---




---
url: /api/elements/built-in/overlay-API.md
---

## Attributes

### `ios-enable-swipe-back`

{' '}

<IOSOnly />

```tsx
// @defaultValue: false
'ios-enable-swipe-back'?: boolean;
```

When overlay is displayed, 'true' allows swiping right to close the current page, 'false' does not allow it

### `level`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
// @defaultValue: 1
level?: 4 | 2 | 1 | 3;
```

Introduces the concept of layers, which are divided into four levels. The larger the layer, the closer it is to the bottom. By default, it is the first level. The layers are arranged in order from 1 to 4. The displayed layer is specified and is not affected by the order of display. Within each layer, the arrangement is based on the 'last in, first out' logic. The layer cannot be dynamically adjusted when the overlay is displayed, and can only be adjusted when it is hidden. \*

### `mode`

{' '}

<IOSOnly />

```tsx
// @defaultValue: 'window'
mode?: string;
```

Specifies the level at which the overlay content resides on iOS. window: Mounted on the window, the top level of the app; top: Mounted on the topViewController; page: Mounted on UINavigationController; others: customize the name of class in the client.

### `visible`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

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

Control whether the overlay is displayed

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `binddismissoverlay`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
binddismissoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is hidden.

### `binderror`

{' '}

<AndroidOnly />

<VersionBadge>
  2.18
</VersionBadge>

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

| Field     | Type   | Optional | Default | Platforms       | Since | Description                                                                                                                                                  |
| --------- | ------ | -------- | ------- | --------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| errorCode | string | No       | –       | <AndroidOnly /> |       | Error code: 0 - Display normally; non-0 - Unable to display, you can try to solve it by using the preloading scheme mentioned below for adapting containers. |
| errorMsg  | string | No       | –       | <AndroidOnly /> |       | Error message                                                                                                                                                |

Callback when touch on the overlay

### `bindoverlaytouch`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

```tsx
bindoverlaytouch = (e: OverlayTouchEvent) => {};
```

| Field | Type              | Optional | Default | Platforms                                | Since | Description                              |
| ----- | ----------------- | -------- | ------- | ---------------------------------------- | ----- | ---------------------------------------- |
| state | OverlayTouchState | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | Touch state                              |
| x     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | x position relative to the window, in px |
| y     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | y position relative to the window, in px |

Callback when touch on the overlay

### `bindrequestclose`

{' '}

<AndroidOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
bindrequestclose = (e: BaseEvent) => {};
```

Callback when the back button is clicked.

### `bindshowoverlay`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
bindshowoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is displayed



---
url: /api/elements/built-in/overlay.md
---

# `<overlay>`

<APISummary />

`<overlay>` is a container that does not participate in page layout. It occupies no space itself and requires neither width nor height.

When rendered, the content inside `<overlay>` is completely detached from the Lynx document flow and promoted to a rendering layer outside of Lynx.

By default, the only child of `<overlay>` uses the screen dimensions as its width and height. It is recommended to treat it as an independent drawing container for the full overlay content.

:::info

**Use cases**

- When embedding a Lynx sub-module in a native page, use `<overlay>` to build a dialog that covers the entire page.
- When the page is built entirely with Lynx, **do not** use `<overlay>`; simply use `position: fixed` instead.

:::

## Usage

### Requirements

- `<overlay>` **can only have one direct child node**.
- `<overlay>` **itself must set `position: fixed`**.

### Recommended Usage

- Use the only child node of `<overlay>` as the backdrop container:
  - Even if the background is transparent, it is still recommended to render it.
  - Explicitly set the size: **`width: 100%; height: 100%`**.
  - Explicitly create an independent stacking context: **`z-index: 0`**.

```tsx
<overlay class="overlay">
  <view class="backdrop">
    // Dialog Content
    <Dialog class="dialog-content" />
  </view>
</overlay>
```

```css
.overlay {
  overflow: visible;
  position: fixed;
}

.backdrop {
  width: 100%;
  height: 100%;
  z-index: 0;
}
```

- To adjust the dialog’s visual size, control it inside the backdrop (e.g. with `margin`) instead of changing the backdrop’s own size.

```css
.dialog-content {
  margin: 100px;
  position: absolute;
}
```

**This is an example below:  overlay**

**Bundle:** `dist/base.lynx.bundle`

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

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

const App = () => {
  const [visible, setVisible] = useState(true);

  return (
    <view
      style={{
        linearOrientation: "vertical",
        width: "100%",
        height: "100%",
        padding: "10px",
      }}
    >
      <overlay visible={visible} style={{ position: "fixed" }}>
        <view
          style={{
            width: "100%",
            height: "100%",
            backgroundColor: "rgba(0, 0, 0, 0.5)",
            display: "flex",
            justifyContent: "center",
            alignItems: "center",
          }}
          bindtap={() => setVisible(false)}
        >
          <view
            catchtap={() => console.log("tap inside the overlay")}
            style={{
              width: "80%",
              height: "50%",
              backgroundColor: "white",
              display: "flex",
              justifyContent: "center",
              alignItems: "center",
              borderRadius: "10px",
            }}
          >
            <text
              style={{
                fontSize: "30px",
                color: "red",
                textAlign: "center",
                width: "max-content",
              }}
            >
              Biz Content
            </text>
            <text
              catchtap={() => setVisible(false)}
              style={{
                position: "absolute",
                fontSize: "20px",
                color: "white",
                textAlign: "center",
                left: "20px",
                right: "20px",
                bottom: "20px",
                backgroundColor: "green",
                padding: "10px",
                borderRadius: "5px",
              }}
            >
              Dismiss
            </text>
          </view>
        </view>
      </overlay>
      <view
        bindtap={() => setVisible(true)}
        style={{
          width: "100%",
          padding: "10px",
          backgroundColor: "#12345678",
          borderRadius: "10px",
        }}
      >
        <text
          style={{
            fontSize: "30px",
            color: "red",
            textAlign: "center",
            width: "max-content",
          }}
        >
          Open the overlay
        </text>
      </view>
    </view>
  );
};

root.render(<App />);

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

```




## Attributes

### `ios-enable-swipe-back`

{' '}

<IOSOnly />

```tsx
// @defaultValue: false
'ios-enable-swipe-back'?: boolean;
```

When overlay is displayed, 'true' allows swiping right to close the current page, 'false' does not allow it

### `level`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
// @defaultValue: 1
level?: 4 | 2 | 1 | 3;
```

Introduces the concept of layers, which are divided into four levels. The larger the layer, the closer it is to the bottom. By default, it is the first level. The layers are arranged in order from 1 to 4. The displayed layer is specified and is not affected by the order of display. Within each layer, the arrangement is based on the 'last in, first out' logic. The layer cannot be dynamically adjusted when the overlay is displayed, and can only be adjusted when it is hidden. \*

### `mode`

{' '}

<IOSOnly />

```tsx
// @defaultValue: 'window'
mode?: string;
```

Specifies the level at which the overlay content resides on iOS. window: Mounted on the window, the top level of the app; top: Mounted on the topViewController; page: Mounted on UINavigationController; others: customize the name of class in the client.

### `visible`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

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

Control whether the overlay is displayed

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `binddismissoverlay`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
binddismissoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is hidden.

### `binderror`

{' '}

<AndroidOnly />

<VersionBadge>
  2.18
</VersionBadge>

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

| Field     | Type   | Optional | Default | Platforms       | Since | Description                                                                                                                                                  |
| --------- | ------ | -------- | ------- | --------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| errorCode | string | No       | –       | <AndroidOnly /> |       | Error code: 0 - Display normally; non-0 - Unable to display, you can try to solve it by using the preloading scheme mentioned below for adapting containers. |
| errorMsg  | string | No       | –       | <AndroidOnly /> |       | Error message                                                                                                                                                |

Callback when touch on the overlay

### `bindoverlaytouch`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

```tsx
bindoverlaytouch = (e: OverlayTouchEvent) => {};
```

| Field | Type              | Optional | Default | Platforms                                | Since | Description                              |
| ----- | ----------------- | -------- | ------- | ---------------------------------------- | ----- | ---------------------------------------- |
| state | OverlayTouchState | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | Touch state                              |
| x     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | x position relative to the window, in px |
| y     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | y position relative to the window, in px |

Callback when touch on the overlay

### `bindrequestclose`

{' '}

<AndroidOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
bindrequestclose = (e: BaseEvent) => {};
```

Callback when the back button is clicked.

### `bindshowoverlay`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```tsx
bindshowoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is displayed

## Compatibility

**Compatibility Table**
**Query:** `elements.overlay`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |
| HarmonyOS | 3.5 | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Clay macOS | 3.5 | - |
| Web | ❌ No | - |

**Description:** overlay




---
url: /api/elements/built-in/page.md
---

# `<page>`

`<page>` element is the root node, only one `<page>` element is allowed per page. You can omit the explicit `<page>` wrapper, as the frontend framework will generate the root node by default.

## Usage

### Omitting the `<page>` Element

By default, you don't need to manually add the `<page>` element as the frontend framework generates the root node automatically.

In this case, while direct `style` and `class` attributes cannot be set explicitly, you can still style the root node using [`page`](/api/css/selectors.md#using-page-to-select-the-root-node) and [`:root`](/api/css/selectors.md#root-selector) selectors, or select it via [`SelectorQuery:selectRoot()`](/api/lynx-api/selector-query/selector-query-select-root.md).

```css
/* use `page` selector */
page {
  background-color: white;
}

/* or you can use `:root` selector */
:root {
  background-color: white;
}
```

**This is an example below:  page**

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

```scss {1-3,5-8}
:root {
  background: linear-gradient(120deg, rgb(255, 53, 26), rgb(0, 235, 235));
}

page {
  border: 10px solid black;
  border-radius: 20px;
}

.title {
  font-size: 20px;
  font-weight: bold;
}

```



### Using `<page>` Element Explicitly

For more flexibility in styling the root node or binding events, you can add `<page>` as the outermost element. It works similarly to `<view>` and supports all its styles and attributes except for `width`, `height`, and `position`. See [No Direct Size Modification](#no-direct-size-modification) for details.

```jsx {3,7}
const App = () => {
  return (
    <page className="body" bindtap={handlePageClick}>
      <view style={{ width: '100%', height: '100%' }}>
        <text className="title">Page Example</text>
      </view>
    </page>
  );
};
```

Similar to `<view>`, you can add `style`, `class` and bind events to `<page>`. Note that you can only have one `<page>` element.

**This is an example below:  page**

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

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

const App = () => {
  const [showPopup, setShowPopup] = useState(false);

  const handlePageClick = () => {
    setShowPopup(prev => !prev);
  };

  return (
    <page className="container" bindtap={handlePageClick}>
      <view
        style={{
          width: "100%",
          height: "100%",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        <text className="title">Use Page Element Example, Click it</text>
      </view>
      {showPopup && (
        <view className="popup">
          <text className="popup-text">Click Response</text>
        </view>
      )}
    </page>
  );
};

root.render(<App />);

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

```



### No Direct Size Modification

The size constraints of `<page>` element are specified by its parent [native view](/guide/embed-lynx-to-native.md#Constraining-LynxView). You cannot directly modify its `width`, `height`, `left`, or `top` styles through `style` or `class`. This design allows Lynx pages to be embedded into native views, enabling better adaptation to the native app's layout flow.



---
url: /api/elements/built-in/scroll-view-API.md
---

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



---
url: /api/elements/built-in/scroll-view.md
---

# `<scroll-view>`

<APISummary />

Basic scrolling component supporting both horizontal and vertical scrolling. When its content area is larger than its visible area, it allows users to scroll to reveal more content.

## Usage

### Horizontal and Vertical Scrolling

`<scroll-view>` supports both horizontal and vertical scrolling, implemented through the `scroll-orientation` properties.
`<scroll-view>` always uses the [linear](/guide/ui/layout/linear-layout.md) layout, and the layout direction is determined by the `scroll-orientation` attributes.

**This is an example below:  scroll-view**

**Entry:** `src/base`
**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {15,24}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { VerticalScrollItem } from "../component/scrollItem.jsx";
import { HorizontalScrollItem } from "../component/scrollItem.jsx";

export const App = () => {
  return (
    <view style={{ width: "100%", height: "100%", padding: 10, display: "linear", marginTop: 20 }}>
      <text style={{ fontSize: "20px", fontWeight: "bold", height: "40px", paddingLeft: "10px", marginTop: "10px" }}>
        Horizontal ScrollView Example
      </text>
      <scroll-view
        scroll-orientation="horizontal"
        style={{ width: "calc(100% - 10px)", height: "100px", paddingLeft: "5px", borderRadius: "10px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => <HorizontalScrollItem index={index} />)}
      </scroll-view>
      <text style={{ fontSize: "20px", fontWeight: "bold", height: "40px", paddingLeft: "10px", marginTop: "10px" }}>
        Vertical ScrollView Example
      </text>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px", marginLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => <VerticalScrollItem index={index} />)}
      </scroll-view>
    </view>
  );
};

```



### Scroll Events

Use event callbacks such as [`bindscroll`](#bindscroll), [`bindscrolltoupper`](#bindscrolltoupper), and [`bindscrolltolower`](#bindscrolltolower) to monitor changes in scroll progress.

**This is an example below:  scroll-view**

**Entry:** `src/event`
**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {16-24}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root } from "@lynx-js/react";
import "./index.css";
import { VerticalScrollItem } from "../component/scrollItem.jsx";
const VerticalScrollContainer = () => {
  return (
    <view
      style={{ width: "100%", height: "100%" }}
    >
      <text className="title">ScrollView Example</text>
      <scroll-view
        scroll-orientation="vertical"
        style="width:100%; height: 100%; padding-left: 5px;margin-left:5px"
        bindscroll={(e) => {
          console.log(e.detail);
        }}
        bindscrolltoupper={(e) => {
          console.log(e.detail);
        }}
        bindscrolltolower={(e) => {
          console.log(e.detail);
        }}
      >
        {Array.from({ length: 20 }).map((item, index) => <VerticalScrollItem index={index} />)}
      </scroll-view>
    </view>
  );
};
export default VerticalScrollContainer;
root.render(<VerticalScrollContainer />);

```



### Sticky Capability

As a child node of `<scroll-view>`, you can set the `sticky` attribute making the child node remain at a certain distance from the top of the `<scroll-view>` and not continue scrolling with the content.

**This is an example below:  scroll-view**

**Entry:** `src/sticky`
**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root } from "@lynx-js/react";
import { VerticalScrollItem } from "../component/scrollItem.jsx";
import { StickyItem } from "./stickyItem.jsx";

const VerticalScrollContainer = () => {
  return (
    <view style={{ width: "100%", height: "100%" }}>
      <text className="title">ScrollView Example</text>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px", marginTop: "5px", marginLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => {
          if (index == 2) {
            return <StickyItem index={index} height={100} sticky={true} />;
          }
          return <VerticalScrollItem index={index} />;
        })}
      </scroll-view>
    </view>
  );
};
export default VerticalScrollContainer;
root.render(<VerticalScrollContainer />);

```



:::tip
`sticky`
 can only be set for direct child nodes of `<scroll-view>`
. On <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




---
url: /api/elements/built-in/text.md
---

# `<text>`

<APISummary />

`<text>` is a built-in element in Lynx used to display text content. It supports specifying text style, binding click event callbacks, and can nest `<text>`, [`<image>`](/api/elements/built-in/image.md), and [`<view>`](/api/elements/built-in/view.md) elements to achieve relatively complex text and image content presentation.

## Usage

The `<text>` element has its own layout context similar to the Web's [inline formatting context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_inline_layout/Inline_formatting_context). It does not support `display` properties like `<view>`. For advanced text styling with `<text>` element, see the [Text and Typography guide](/guide/styling/text-and-typography.md).

### Nested `<text>`

Nested `<text>` refers to `<text>` subelements within a `<text>` element.

**This is an example below:  text**

**Entry:** `src/inline_text`
**Bundle:** `dist/inline_text.lynx.bundle` | Web: `dist/inline_text.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MyComponent = () => {
  return (
    <view className="fixed_area" data-test-tag="container">
      <view className="test-item">
        <text className="text">Case 1：inline-text Concatenate:</text>
        <text className="expection">
          <text>simple text scenario:</text>
          <text>[inline-text 1]</text>
          <text>[inline-text 2]</text>
        </text>
      </view>

      <view className="test-item" style={{ marginTop: "40px" }}>
        <text className="text">Case 2：inline-text: different color</text>
        <text className="expection">
          <text>simple text scenario:</text>
          <text style={{ color: "blue" }}>[inline-text 1]</text>
          <text style={{ color: "#62efff" }}>[inline-text 2]</text>
        </text>
        <text className="expection">
          <text>inline-text gradient-color:</text>
          <text style={{ color: "blue" }}>[inline-text 1]</text>
          <text
            style={{
              color: "linear-gradient(to right, red, #65499c, #62efff)",
            }}
          >
            [inline-text 2]
          </text>
        </text>
      </view>

      <view className="test-item" style={{ marginTop: "40px" }}>
        <text className="text">Case 3：inline-text: different style</text>
        <text className="expection">
          <text>simple text scenario:</text>
          <text style={{ fontStyle: "italic" }}>[inline-text 1]</text>
          <text style={{ textDecoration: "line-through" }}>
            [inline-text 2]
          </text>
        </text>
        <text className="expection">simple text scenario</text>
      </view>
    </view>
  );
};
export default MyComponent;
root.render(<MyComponent />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Since the [CSS inheritance is not enabled](/guide/styling/custom-theming.md#leveraging-css-inheritance-as-needed) by default in Lynx, it's recommended to explicitly declare the required styles for `<text>`, as it will not inherit the text-related properties from its parent node.

```tsx
// When CSS inheritance is not enabled, the font-size of the parent node will not be applied to the child <text> node.
<view style={{ fontSize: '20px' }}>
  <text>hello world</text>
</view>
```

However, nested `<text>` is special. Even when CSS inheritance is not enabled, it will still apply `<color>` and `<font-family>` properties of the parent `<text>`. To maintain consistency, it is recommended to explicitly override the properties of the parent `<text>` in the inline `<text>`.

```tsx
<text style={{ color: 'red' }}>
  red
  <text>red</text>
  <text style={{ color: 'blue' }}>blue</text>
</text>
```

### Nested `<image>`

Nested `<image>` refers to `<image>` subelements within a `<text>` element. It can be used for mixed text and image layout.

**This is an example below:  text**

**Entry:** `src/inline_image`
**Bundle:** `dist/inline_image.lynx.bundle` | Web: `dist/inline_image.web.bundle`

```tsx
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
export default class Index extends Component {
  render() {
    return (
      <view style={{ width: "200px" }}>
        <text style={{ fontSize: "20px", textAlign: "center" }}>
          <image
            style={{
              width: "20px",
              height: "20px",
              border: "1px solid red",
              borderRadius: "50%",
              verticalAlign: "middle",
            }}
            src={ExclamationCircle}
          />
          <text style={{}}>
            This is a warning message.This is a warning message.This is a warning message.
          </text>
        </text>
      </view>
    );
  }
}
root.render(<Index />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Nested `<view>`

A `<view>` written inside a text element will have inline characteristics and participate in text layout. It also supports all functionalities of the `<view>` tag, including adding borders, rounded corners, and any other element content inside it.

**This is an example below:  text**

**Entry:** `src/inline_view`
**Bundle:** `dist/inline_view.lynx.bundle` | Web: `dist/inline_view.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
import "./index.scss";

const InlineView = () => {
  return (
    <view
      style="flex-direction:column;align-items:center;border:1px red solid;"
      lynx-test-tag="container"
    >
      <text
        style="text-align:center;font-size:25px;text-overflow:ellipsis;"
        text-maxline="2"
      >
        <view
          style={{ flexDirection: "column", verticalAlign: "center" }}
          className="container"
          clip-radius="true"
        >
          <view className="title-name-wrapper-border">
            <view className="title-name-wrapper-border-before"></view>
            <view className="title-name-wrapper-border-after"></view>
          </view>
        </view>
        This is a paragraph containing animation.This is a paragraph containing animation.
      </text>
    </view>
  );
};

export default InlineView;
root.render(<InlineView />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### `<inline-truncation>`

`<inline-truncation>` tag is used to customize the content that needs to be displayed at the end of the text when truncation occurs.

**This is an example below:  text**

**Entry:** `src/inline_truncation`
**Bundle:** `dist/inline_truncation.lynx.bundle` | Web: `dist/inline_truncation.web.bundle`

```tsx
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";
import RightArrow from "@assets/image/rightarrow.png?inline";
import { root } from "@lynx-js/react";

const InlineTruncation = () => {
  return (
    <view style={{ width: "200px" }}>
      <text style={{ height: "30px", lineHeight: "20px" }} text-maxline="1">
        this is a test text. this is a test text. this is a test text.this is a test text. this is a test text. this is
        a test text.
        <inline-truncation>
          <text>...See More</text>
          <image src={RightArrow} style={{ width: "10px", height: "10px" }} />
        </inline-truncation>
      </text>

      <text
        style={{ lineHeight: "20px", marginTop: "30px" }}
        text-maxline={"2"}
      >
        this is a test text. this is a test text. this is a test text.this is a test text. this is a test text. this is
        a test text.
        <inline-truncation>
          <text style={{ color: "grey" }}>...See More</text>
          <view style={{ verticalAlign: "center" }} flatten={false}>
            <image
              src={ExclamationCircle}
              style={{ width: "15px", height: "15px" }}
            />
          </view>
        </inline-truncation>
      </text>
    </view>
  );
};

export default InlineTruncation;
root.render(<InlineTruncation />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### RTL

The `text` element supports RTL (Right-To-Left) language layout display. By default, the `text` element will determine the text language based on the content and use the corresponding layout method. Developers can also specify the use of RTL layout by setting the `direction` style.

:::tip

When `direction` is set to `rtl` or `lynx-rtl`, `text-align:start` will be converted to `text-align:right`, and similarly, `text-align:end` will be converted to `text-align:left`.
When `direction` is set to `lynx-rtl`, `text-align:left` will be converted to `text-align:right`, and similarly, `text-align:right` will be converted to `text-align:left`.

:::

**This is an example below:  text**

**Entry:** `src/text_style`
**Bundle:** `dist/text_style.lynx.bundle` | Web: `dist/text_style.web.bundle`

```tsx {303-356}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import "./index.scss";
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";

const AlignContent = () => {
  const examples = [
    { type: "text-overflow" },
    { type: "text-vertical-align" },
    { type: "text-decoration" },
    { type: "text-shadow" },
    { type: "text-direction-rtl" },
  ];

  const TextOverflowExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            fontSize: "20px",
          }}
        >
          text overflow:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text className="item clip" text-maxline="1">
            Hello World Hello World Hello World
          </text>
          <text className="item ellipsis" text-maxline="1">
            Hello World Hello World Hello World
          </text>
        </view>
      </view>
    );
  };

  const TextVerticalAlignExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text vertical align:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              backgroundColor: "tomato",
              lineHeight: "50px",
            }}
            text-maxline="1"
          >
            <text
              style={{
                verticalAlign: "middle" as const,
              }}
            >
              middle
            </text>
            <text
              style={{
                verticalAlign: "center" as const,
              }}
            >
              center
            </text>
            <text
              style={{
                verticalAlign: "top" as const,
              }}
            >
              top
            </text>
            <text
              style={{
                verticalAlign: "bottom" as const,
              }}
            >
              bottom
            </text>
            <text
              style={{
                verticalAlign: "text-top" as const,
              }}
            >
              text-top
            </text>
            <text
              style={{
                verticalAlign: "baseline" as const,
              }}
            >
              baseline
            </text>
          </text>
          <text
            style={{
              marginTop: "10px",
              backgroundColor: "orange",
              lineHeight: "50px",
            }}
            text-maxline="1"
          >
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "middle" as const,
              }}
            >
              <text>middle</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "center" as const,
              }}
            >
              <text>center</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "top" as const,
              }}
            >
              <text>top</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "bottom" as const,
              }}
            >
              <text>bottom</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "texttop" as const,
              }}
            >
              <text>text-top</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "baseline" as const,
              }}
            >
              <text>baseline</text>
            </view>
          </text>
        </view>
      </view>
    );
  };

  const TextDecorationExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text decoration:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              backgroundColor: "#ccc",
              marginTop: "10px",
            }}
          >
            text-decoration
          </text>
          <text
            style={{
              textDecoration: "none" as const,
            }}
          >
            none
          </text>
          <text
            style={{
              textDecoration: "underline" as const,
            }}
          >
            underline
          </text>
          <text
            style={{
              textDecoration: "line-through" as const,
            }}
          >
            line-through
          </text>
          <text
            style={{
              textDecoration: "underline line-through red solid" as const,
            }}
          >
            red solid
          </text>
          <text
            style={{
              textDecoration: "underline line-through green dotted" as const,
            }}
          >
            green dotted
          </text>
          <text
            style={{
              textDecoration: "underline line-through blue dashed" as const,
            }}
          >
            blue dashed
          </text>
        </view>
      </view>
    );
  };

  const TextShadowExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text shadow:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              backgroundColor: "#ccc",
              marginTop: "10px",
            }}
          >
            Text Shadow Properties
          </text>
          <text
            style={{
              textShadow: "none" as const,
            }}
          >
            text-shadow: none;
          </text>
          <text
            style={{
              textShadow: "1px 1px 2px #558abb" as const,
            }}
          >
            text-shadow: 1px 1px 2px #558abb;
          </text>
          <text
            style={{
              textShadow: "1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue" as const,
            }}
          >
            text-shadow: 1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue;
          </text>
          <text
            style={{
              textShadow: "0 .005px .01rem rgba(70, 70, 70, .3)" as const,
            }}
          >
            text-shadow: 0 .005px .01rem rgba(70, 70, 70, .3);
          </text>
        </view>
      </view>
    );
  };

  const TextDirectionRtlExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text direction rtl:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              direction: "rtl" as const,
            }}
          >
            لإعادة الشحن على دون دفع رسوم الخدمة داخل
            <image
              src={ExclamationCircle}
              style={{
                width: "22px",
                height: "22px",
              }}
            />
            رسوم الخدمة داخل
            <view
              style={{
                padding: "10px",
                border: "1px solid red",
                borderRadius: "20px",
              }}
            >
              <text
                style={{
                  fontSize: "30px",
                  color: "linear-gradient(green, yellow)",
                }}
              >
                {" "}
                sub text{" "}
              </text>
            </view>
            الشحن على دون دفع
          </text>
        </view>
      </view>
    );
  };

  const renderExample = (type: string) => {
    switch (type) {
      case "text-overflow":
        return <TextOverflowExample />;
      case "text-vertical-align":
        return <TextVerticalAlignExample />;
      case "text-decoration":
        return <TextDecorationExample />;
      case "text-shadow":
        return <TextShadowExample />;
      case "text-direction-rtl":
        return <TextDirectionRtlExample />;
      default:
        return null;
    }
  };

  return (
    <scroll-view
      scroll-orientation="vertical"
      style={{
        padding: "5px",
        width: "100%",
        height: "100%",
      }}
    >
      {examples.map((example, index) => renderExample(example.type))}
    </scroll-view>
  );
};

export default AlignContent;

root.render(<AlignContent />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Attributes

Attribute names and values are used to describe the behavior and appearance of elements.

### `text-maxline`

```tsx
// DefaultValue: '-1'
text-maxline?: number;
```

Limits the maximum number of lines displayed for the text content, `overflow:hidden` should be set simultaneously.

### `include-font-padding`
 <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(
          {
            query: true,
            id: true,
          },
          (result) => resolve(result.map(({ query }) => query)),
        )
        .exec();
    });

    Promise.all(
      resArray.map((selectorQuery) => {
        return new Promise<{
          top: number;
          left: number;
          width: number;
          height: number;
          id: string;
        }>((resolve, reject) => {
          selectorQuery.selectRoot()
            .invoke({
              method: "boundingClientRect",
              success: resolve,
              fail: reject,
            })
            .exec();
        });
      }),
    ).then((values) => {
      textsInfo = values.map(({ top, left, width, height, id }) => ({
        id,
        left,
        top,
        width,
        height,
        startX: -1,
        startY: 0,
        endX: width,
        endY: height,
      }));
    });
  }

  // Function to execute text selection on a specific node
  function execSelection(
    node: TextNodeInfo,
    startX: number,
    startY: number,
    endX: number,
    endY: number,
    showStartHandle = true,
    showEndHandle = true,
  ) {
    lynx
      .createSelectorQuery()
      .select(`#${node.id}`)
      .invoke({
        method: "setTextSelection",
        params: {
          startX,
          startY,
          endX,
          endY,
          showStartHandle,
          showEndHandle,
        },
        success(res) {
          if (!res) {
            return;
          }
          const boxes = res.boxes || [];
          const hs = res.handles || [];
          if (Array.isArray(boxes) && boxes.length > 0) {
            node.startX = boxes[0].left;
            node.startY = boxes[0].top + boxes[0].height / 2;
            node.endX = boxes[boxes.length - 1].left + boxes[boxes.length - 1].width;
            node.endY = boxes[boxes.length - 1].top + boxes[boxes.length - 1].height / 2;
          } else {
            node.startX =
              node.startY =
              node.endX =
              node.endY =
                -1;
          }
          showStartHandle && (handlers[0] = { ...hs[0], startX: node.startX, startY: node.startY });
          showEndHandle && (handlers[1] = { ...hs[1], startX: node.endX, startY: node.endY });
        },
      })
      .exec();
    if (startX === -1) {
      node.startX = -1;
      handlers = [];
    }
  }

  // Function to set the text selection based on the start and end coordinates
  function setSelection(x1: number, y1: number, x2: number, y2: number) {
    const [[startX, startY], [endX, endY]] = [
      [x1, y1],
      [x2, y2],
    ].sort((a, b) => {
      if (a[1] === b[1]) {
        return a[0] - b[0];
      }
      return a[1] - b[1];
    });
    const clear: TextNodeInfo[] = [];
    const update: TextNodeInfo[] = [];
    for (const node of textsInfo) {
      if (
        (startY < node.top && node.top + node.height < endY)
        || (node.left <= startX && startX <= node.left + node.width && node.top <= startY
          && startY <= node.top + node.height)
        || (node.left <= endX && endX <= node.left + node.width && node.top <= endY && endY <= node.top + node.height)
      ) {
        update.push(node);
      } else if (node.startX !== -1) {
        clear.push(node);
      }
    }
    if (clear.length > 0 || update.length > 0) {
      for (const node of clear) {
        execSelection(node, -1, -1, -1, -1, false, false);
      }
      const start = update[0];
      const end = update[update.length - 1];
      if (update.length === 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          Math.min(start.width, endX - start.left),
          Math.min(start.height, endY - start.top),
          true,
          true,
        );
      } else if (update.length > 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          start.width,
          start.height,
          true,
          false,
        );
        for (let i = 1; i < update.length - 1; i++) {
          execSelection(update[i], 0, 0, update[i].width, update[i].height, false, false);
        }
        execSelection(
          end,
          0,
          0,
          Math.min(end.width, endX - end.left),
          Math.min(end.height, endY - end.top),
          false,
          true,
        );
      }
      return true;
    }
    return false;
  }

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view
          id="container"
          style={{ width: "90vw" }}
          className="Container"
          bindlongpress={handleLongPress}
          bindtouchstart={handleTouchStart}
          bindtouchmove={handleTouchMove}
          bindtouchend={handleTouchEnd}
          bindtap={handleTap}
        >
          <text id="0" text-selection={true} custom-text-selection={true} flatten={false} className="Title">
            This is title
          </text>
          <view className="SplitLine" />
          <text id="1" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            1.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="2" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            2.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="3" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            3.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
        </view>
      </view>
    </page>
  );
};

export default CrossTextSelection;

root.render(<CrossTextSelection />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



2. Bind Gesture Events on the Wrapper `<view>`

Bind long-press, tap, and touch events on the outer `<view>` container. These will be used to control your custom selection and gesture logic.

```jsx
<view
  id="container"
  style={{ width: '90vw' }}
  className="Container"
  bindlongpress={handleLongPress}
  bindtouchstart={handleTouchStart}
  bindtouchmove={handleTouchMove}
  bindtouchend={handleTouchEnd}
  bindtap={handleTap}
>
  <text
    id="0"
    text-selection={true}
    custom-text-selection={true}
    flatten={false}
    className="Title"
  >
    This is title
  </text>
  <view className="SplitLine" />
</view>
```

3. Handle Selection and Copying Logic

- On component mount, retrieve metadata for all selectable `<text>` nodes, including their ID, dimensions, and positions:

```jsx
const CrossTextSelection = () => {
  useEffect(() => {
    getTextNodeRect();
}, []);

// Asynchronous function to get the bounding rectangles of text nodes
async function getTextNodeRect() {
  // 1.Use lynx.createSelectorQuery () to get the required text node.
  // 2.Call boundingClientRect method of the text node to get the rect of the node.
}

```

- On Long Press: Start Selection
  `handleLongPress()` is triggered on long press. It initiates the selection state, records the starting point, and performs the first selection update:

```jsx
// Handle long press event to start text selection
const handleLongPress = (e) => {
  isSelecting = true;
  startPosition.x = e.detail.x;
  startPosition.y = e.detail.y;
  setSelection(e.detail.x, e.detail.y, e.detail.x, e.detail.y);
};
```

- On Drag: Update Selection Area in Real Time

As the user drags, `handleTouchMove()` is called. If a selection is in progress, it updates the highlighted area accordingly:

```jsx
// Handle touch move event to update the selection area
const handleTouchMove = (e) => {
  if (isSelecting) {
    setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
  }
};
```

- On Finger Release: Finalize Selection

`handleTouchEnd()` is triggered on finger release. This finalizes the selected region and exits selection mode:

```jsx
// Handle touch end event to finalize the selection
const handleTouchEnd = (e) => {
  if (isSelecting) {
    setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
  }
  isSelecting = false;
};
```

On Tap Blank Area: Clear Selection

Tapping outside the text elements triggers a selection clear:

```jsx
// Handle tap event to clear the selection
const handleTap = (e) => {
  if (handlers.length === 0) {
    return;
  }
  setSelection(-1, -1, -1, -1);
};
```

- On Handle Drag: Adjust Selection Range

In `handleTouchStart()`, determine if the touch point is near one of the draggable handles. If so, allow real-time adjustment of the selection:

```jsx
// Handle touch start event to check if the touch is on a handler
const handleTouchStart = (e) => {
  if (handlers.length === 0) {
    return;
  }
  const { x, y } = e.detail;
  for (const [index, handler] of handlers.entries()) {
    if (
      Math.pow(handler.x - x, 2) + Math.pow(handler.y - y, 2) <
      Math.pow(handler.radius, 2)
    ) {
      isSelecting = true;
      const another = handlers[(index + 1) % 2];
      startPosition = { x: another.startX, y: another.startY };
      break;
    }
  }
};
```

## Compatibility

### `<text>`

**Compatibility Table**
**Query:** `elements.text`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>text</code>


### Nested `<text>`

**Compatibility Table**
**Query:** `elements.nested-text`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** nested <code>text</code>


### nested `<image>`

**Compatibility Table**
**Query:** `elements.nested-image`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** nested <code>image</code>


### `<inline-truncation>`

**Compatibility Table**
**Query:** `elements.inline-truncation`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>inline-truncation</code>




---
url: /api/elements/built-in/textarea-API.md
---

## 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

```
```



---
url: /api/elements/built-in/textarea.md
---

# `<textarea>`

<APISummary />


`<textarea>` is used to create interactive input controls that allow users to input and edit multi-line text.

:::tip

This feature requires the client to add additional dependencies. Please refer to [More Elements](/guide/start/integrate-with-existing-apps.md) for the integration method.

:::

## Usage

### Basic

Below is a basic usage example of the `<textarea>` component:

**This is an example below:  textarea**

**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {13-21}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "20px" }}>
      <view style={{ width: "100%", padding: "10px", backgroundColor: "#87654321", borderRadius: "10px" }}>
        <textarea
          style={{ width: "100%", color: "blue", fontSize: "50px" }}
          placeholder="Title"
          maxlines={2}
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>

      <view
        style={{
          width: "100%",
          padding: "10px",
          marginTop: "20px",
          backgroundColor: "#12345678",
          borderRadius: "10px",
        }}
      >
        {
          <textarea
            style={{ width: "100%", height: "300px", fontSize: "30px" }}
            placeholder="Content"
            bindinput={(res: any) => {
              console.log(res.detail.value);
              setInputContent(res.detail.value);
            }}
          />
        }
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Custom Placeholder Style

`<textarea>` can customize its style using the `::placeholder` pseudo-element:

**This is an example below:  textarea**

**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {13-21}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import "./index.scss";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "20px" }}>
      <text style={{ fontSize: "15px" }}>Customized Placeholder And Caret Color</text>
      <view
        style={{
          width: "100%",
          padding: "10px",
          backgroundColor: "#87654321",
          borderRadius: "10px",
          marginTop: "20px",
        }}
      >
        <textarea
          style={{ width: "100%" }}
          placeholder=".textarea::placeholder {
                              color: oragne
                            }"
          class="textarea"
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```




## Attributes

### `android-fullscreen-mode`

{' '}

<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




---
url: /api/elements/built-in/view.md
---

# `<view>`

<APISummary />

A container element similar to HTML's `<div>`. Like `<div>`, `<view>` is a versatile container element that can hold other elements and serves as the foundation for building layouts. All attributes, events, and methods available on `<view>` can be used by other elements.

## Usage

### As a Drawing Container

**This is an example below:  view**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {7-22}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ReactElement } from "react";

const RenderExample = () => {
  return (
    <view
      style={{
        borderLeftWidth: "15px",
        borderRightWidth: "60px",
        borderTopWidth: "100px",
        borderBottomWidth: "50px",
        borderColor: "green red",
        backgroundColor: "blue",
        width: "100vw",
        height: "500px",
      }}
    />
  );
};

const LayoutExample = () => {
  return (
    <view
      style={{
        width: "100vw",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        marginTop: "100px",
      }}
    >
      <text
        style={{
          fontSize: "50px",
          padding: "30px",
          background: "red",
        }}
      >
        Hello World
      </text>
      <text
        style={{
          fontSize: "50px",
          marginTop: "50px",
          padding: "30px",
          background: "green",
        }}
      >
        Hello Lynx
      </text>
    </view>
  );
};

export const App = () => {
  const examples: ReactElement[] = [
    <RenderExample />,
    <LayoutExample />,
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">View Examples</text>
      {examples.map((example, index) => example)}
    </scroll-view>
  );
};

```



### As a Layout Container

**This is an example below:  view**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {24-56}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ReactElement } from "react";

const RenderExample = () => {
  return (
    <view
      style={{
        borderLeftWidth: "15px",
        borderRightWidth: "60px",
        borderTopWidth: "100px",
        borderBottomWidth: "50px",
        borderColor: "green red",
        backgroundColor: "blue",
        width: "100vw",
        height: "500px",
      }}
    />
  );
};

const LayoutExample = () => {
  return (
    <view
      style={{
        width: "100vw",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        marginTop: "100px",
      }}
    >
      <text
        style={{
          fontSize: "50px",
          padding: "30px",
          background: "red",
        }}
      >
        Hello World
      </text>
      <text
        style={{
          fontSize: "50px",
          marginTop: "50px",
          padding: "30px",
          background: "green",
        }}
      >
        Hello Lynx
      </text>
    </view>
  );
};

export const App = () => {
  const examples: ReactElement[] = [
    <RenderExample />,
    <LayoutExample />,
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">View Examples</text>
      {examples.map((example, index) => example)}
    </scroll-view>
  );
};

```



## Attribute

Attributes and their values are used to describe the behavior and appearance of elements.

### `name`

```ts
// DefaultValue undefined
name?: string
```

Used to specify the name of the element, generally for native to operate the corresponding node from the native side through `findViewByName`.

### `id`

```ts
// DefaultValue undefined
id?: string;
```

Used to specify the unique identity of the element, which can be used by the front-end API to find and operate the corresponding node, such as [`invoke`](/api/lynx-api/nodes-ref/nodes-ref-invoke.md).

```ts
id?: string;
```

### `style`

```ts
style?: string;
```

Used to apply inline styles to elements.

### `class`

```ts
class?: string;
```

Used to specify one or more class names for an element, which can be used in CSS to apply styles.

### `className`
 <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




---
url: /api/engine/element-api.md
---

This section aims to introduce the [Element PAPI](/guide/spec.md#elementscomponents-element-papi) currently exposed to the front-end framework. It includes the functions of these APIs and their capability boundaries. Based on this document, the developers can develop the front-end framework. Additionally, based on this, we will discuss how the Element PAPI can be further iterated.



---
url: /api/engine/element-api/__AddClass.md
---

# `__AddClass`

## Introduction

Adds a class selector to the Element object without affecting existing class selectors.

## Syntax

```jsx
__AddClass(element: Element, className: string) : void;
```

### Parameters

|    Key    | Description                        |
| :-------: | ---------------------------------- |
|  element  | Any Element object.                |
| className | The new className, of type string. |

### Return Value

No return value.

## Example

The frontend framework can compile the corresponding frontend tag into the following render directive during the compilation phase.

```jsx
<view src="xxx" class="A B C" />
```

```tsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__AddClass(element, 'A');
__AddClass(element, 'B');
__AddClass(element, 'C');
```



---
url: /api/engine/element-api/__AddConfig.md
---

# `__AddConfig`

## Introduction

Adds a config key and config value to the Element object.

## Syntax

```jsx
__AddConfig(element: Element, type: string, value: any) : void;
```

### Parameters

|   Key   | Description                                          |
| :-----: | ---------------------------------------------------- |
| element | Any Element object.                                  |
|   type  | A case-sensitive string representing the config key. |
|  value  | The config value, which can be of any type.          |

::: tip Note
Developers can set some custom configs for the Element to facilitate extensions by the frontend framework.
:::

### Return Value

No return value.

## Example

The frontend framework can generate render directives in the following way.

```jsx
<view src="xxx" bindtap="onTap" />
```

```tsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__AddConfig(element, 'anyConfig', {});
```



---
url: /api/engine/element-api/__AddDataset.md
---

# `__AddDataset`

## Introduction

Adds a data- attribute to the Element object without affecting existing data- attributes.

## Syntax

```jsx
__AddDataset(element: Element, key: string, value: any) : void;
```

### Parameters

|   Key   | Description                                           |
| :-----: | ----------------------------------------------------- |
| element | Any Element object.                                   |
|   key   | A case-sensitive string representing the dataset key. |
|  value  | The dataset value, which can be of any type.          |

### Return Value

No return value.

## Example

The frontend framework can generate render directives in the following way.

```jsx
<view src="xxx" data-key="value" />
```

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__AddDataset(element, 'key', 'value');
```



---
url: /api/engine/element-api/__AddEvent.md
---

# `__AddEvent`

## Introduction

Adds an Event Listener to the Element object.

## Syntax

```jsx
__AddEvent(element: Element, type: string, name: string, listener: string|Function) : void;
```

### Parameters

|    Key   | Description                                                                  |
| :------: | ---------------------------------------------------------------------------- |
|  element | Any Element object.                                                          |
|   type   | A case-sensitive string representing the type of the event to listen for.    |
|   name   | A case-sensitive string representing the name of the event to listen for.    |
| listener | The listener can be a case-sensitive string, or it can be null or undefined. |

- When the listener is a case-sensitive string, upon triggering the listened event, the Lynx SDK will send the current Element's `parentComponentUniqueID`, `listener`, and `event` to the background thread.
- When the listener is null or undefined, the Lynx SDK will remove the corresponding listener for the specified type and name from the Element object.

::: tip Note
Due to limitations of the Lynx SDK, currently, only one listener can be added for the same type and name. Adding a listener with the same type and name again will overwrite the previously added listener.
:::

### Return Value

No return value.

## Example

The frontend framework can generate render directives in the following way.

```jsx
<view src="xxx" bindtap="onTap" />
```

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__AddEvent(element, 'bindEvent', 'tap', 'onTap');
```



---
url: /api/engine/element-api/__AddInlineStyle.md
---

# `__AddInlineStyle`

## Introduction

Adds inline styles to the Element object.

## Syntax

```jsx
__AddInlineStyle(element: Element, id: number, value: string|null|undefined) : void;
```

### Parameters

|   Key   | Description                                                                                                                                                                                                                                                                                                                                  |
| :-----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | Any Element object.                                                                                                                                                                                                                                                                                                                          |
|    id   | A number that corresponds to a style key, for example, 0 corresponds to the style `top`.                                                                                                                                                                                                                                                     |
|  value  | The style value to be set, which can be a string, null, or undefined. When a string is provided, the Lynx SDK will set the corresponding key and value for the Element; if previously set, it will overwrite the previous value. When null or undefined is provided, the Lynx SDK will remove the key from the inline styles of the Element. |

### Return Value

No return value.

## Example

The frontend framework can process the corresponding frontend tags into render directives as shown below.

```jsx
<view src="xxx" style={{ top: '10px' }} />
```

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__AddInlineStyle(element, 0, '10px');
```



---
url: /api/engine/element-api/__AppendElement.md
---

# `__AppendElement`

## Introduction

Inserts an Element object after the last child of the current Element.

## Syntax

```jsx
__AppendElement(parent: Element, child: Element) : Element;
```

### Parameters

|   Key  | Description                                     |
| :----: | ----------------------------------------------- |
| parent | The parent Element object.                      |
|  child | The child Element to be appended to the parent. |

### Return Value

Returns the appended child Element.

## Example

The frontend framework can perform insertion operations as shown below.

```jsx
// main-thread.js
let child = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, child);
```



---
url: /api/engine/element-api/__CreateComponent.md
---

# `__CreateComponent`

## Introduction

Creates a ComponentElement object.

## Syntax

```jsx
__CreateComponent(componentParentUniqueID: number, componentID: string, cssID: Number, entryName: string, name: string, path: string, config: Record<string, any>|null|undefined, info: Record<string, any>|null|undefined): Element;
```

### Parameters

|           Key           | Description                                                                                                                                              |
| :---------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| parentComponentUniqueID | The Unique Component ID of the ComponentElement that creates this Element, which is a number.                                                            |
|       componentID       | The componentID set by the frontend framework for the ComponentElement, which is a case-sensitive string.                                                |
|          cssID          | The CSSFragment ID, which is of type number.                                                                                                             |
|        entryName        | The schema information of the [Lazy Bundle](/guide/spec.md#lazy-bundle) where the current ComponentElement is located, which is a case-sensitive string. |
|           name          | The frontend-defined name of the current ComponentElement, which is a case-sensitive string.                                                             |
|           path          | The frontend path of the current ComponentElement, which is a case-sensitive string.                                                                     |
|          config         | The configuration for the current ComponentElement.                                                                                                      |
|           info          | Some additional information required when creating the ComponentElement; this parameter can be omitted.                                                  |

### Return Value

Returns the ComponentElement.

## Example

The frontend framework can create a ComponentElement in the following way.

```jsx
// main-thread.js
let element = __CreateComponent(0, '1', 1, '', 'name', 'path', {}, {});
```



---
url: /api/engine/element-api/__CreateElement.md
---

# `__CreateElement`

## Introduction

Creates an Element object.

## Syntax

```jsx
__CreateElement(tagName: string, parentComponentUniqueID: number, info?: object) : Element;
```

### Parameters

|           Key           | Description                                                                                                                                                                                                                  |
| :---------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|         tagName         | A string that specifies the type of Element to create, which corresponds to the LynxUI tagName, such as input. Built-in Elements like view, image, etc. cannot use this interface and must use their respective Create APIs. |
| parentComponentUniqueID | The Unique Component ID of the ComponentElement that creates this Element, which is a number.                                                                                                                                |
|           info          | Additional information required when creating the Element; this parameter can be omitted.                                                                                                                                    |

### Return Value

The return value is currently a Value\_RefCounted type of `lepus::Value`, which is implemented as `base::scoped_refptr<Element>`.

::: tip Note
`base::scoped_refptr<Element>` manages the lifecycle of the Element based on reference counting. Therefore, the frontend framework can hold this return value to manage the Element's lifecycle. The Element will only be destroyed when the frontend framework no longer holds it and the Element is removed from the tree.
:::

## Example

The frontend framework can process the corresponding frontend tags into render directives as follows.

```jsx
<input />
```

```jsx
// main-thread.js
let element = __CreateElement('input', 0, {});
```



---
url: /api/engine/element-api/__CreatePage.md
---

# `__CreatePage`

## Introduction

Creates a PageElement object.

## Syntax

```jsx
__CreatePage(componentID: string, cssID: number, info: Record<string, any>|null|undefined) : Element;
```

### Parameters

|     Key     | Description                                                                                                                                                                                                                   |
| :---------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| componentID | The componentID assigned to the PageElement by the frontend framework, which is a case-sensitive string. The PageElement is a special type of ComponentElement that will be detailed later regarding the role of componentID. |
|    cssID    | The CSSFragment ID, which is a number.                                                                                                                                                                                        |
|     info    | Additional information required when creating the PageElement; this parameter can be omitted.                                                                                                                                 |

### Return Value

Returns the PageElement.

## Example

The frontend framework can create a PageElement in the following way.

```jsx
// main-thread.js
let page = __CreatePage('0', 0, {});
```



---
url: /api/engine/element-api/__ElementIsEqual.md
---

# `__ElementIsEqual`

## Introduction

Determines if the two passed Element objects are the same Element.

## Syntax

```jsx
__ElementIsEqual(left: Element, right: Element) : bool;
```

### Parameters

|  Key  | Description                    |
| :---: | ------------------------------ |
|  left | The left node to be compared.  |
| right | The right node to be compared. |

### Return Value

Returns true only when the left and right are the same node.

## Example

The frontend framework can perform the comparison operation as follows.

```jsx
// main-thread.js
let childA = __CreateElement('view', 0, {});

let childB = __CreateElement('view', 0, {});

let isEqual = __ElementIsEqual(childA, childB);
```



---
url: /api/engine/element-api/__FirstElement.md
---

# `__FirstElement`

## Introduction

Returns the first child node of an Element.

## Syntax

```jsx
__FirstElement(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the first child Element of the current Element.

## Example

The frontend framework can retrieve the first child Element of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let first = __FirstElement(element);
```



---
url: /api/engine/element-api/__GetAttributes.md
---

# `__GetAttributes`

## Introduction

Returns all attributes of an Element in the form of a map.

## Syntax

```jsx
__GetAttributes(element: Element) : object;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the attribute map of the current Element, where the map key is the attribute key and the map value is the attribute value.

## Example

The frontend framework can retrieve the attribute map of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

let attributeMap = __GetAttributes(element);
```



---
url: /api/engine/element-api/__GetChildren.md
---

# `__GetChildren`

## Introduction

Returns all child nodes of an Element in order, in the form of an array.

## Syntax

```jsx
__GetChildren(element: Element) : Array<Element>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns all child nodes of the current Element as an array.

## Example

The frontend framework can retrieve all child nodes of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let children = __GetChildren(element);
```



---
url: /api/engine/element-api/__GetClasses.md
---

# `__GetClasses`

## Introduction

Returns all class selectors of an Element in order, in the form of an array.

## Syntax

```jsx
__GetClasses(element: Element) : Array<string>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the class selectors of the current Element as an array.

## Example

The frontend framework can retrieve the class selectors of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__SetClasses(element, 'A B C');

let classNames = __GetClasses(element);
```



---
url: /api/engine/element-api/__GetComponentID.md
---

# `__GetComponentID`

## Introduction

Returns the componentID of a ComponentElement.

## Syntax

```jsx
__GetComponentID(element: Element) : string;
```

### Parameters

|   Key   | Description           |
| :-----: | --------------------- |
| element | Any ComponentElement. |

### Return Value

Returns the componentID of the ComponentElement.

## Example

The frontend framework can retrieve the componentID of a ComponentElement as follows.

```jsx
// main-thread.js
let element = __CreateComponent(0, '1', 1, '', 'name', 'path', {}, {});

let id = __GetComponentID(element);
```



---
url: /api/engine/element-api/__GetComputedStyleByKey.md
---

# `__GetComputedStyleByKey`

<APISummary />

## Introduction

Returns the resolved style value for a CSS property of an element

## Syntax

```jsx
__GetComputedStyleByKey(element: Element, key: string) : string;
```

### Parameters

|   Key   | Description                                                                                                                                                                              |
| :-----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | Any Element object.                                                                                                                                                                      |
|   key   | A string indicating the CSS property key to be retrieved. Keep in mind that not every CSS property is supported. Refer to the Compatibility table to see which properties are supported. |

### Return Value

Resolved style value for a CSS property of specified element.

:::caution
Unlike browser, this PAPI won't trigger document reflow.
:::

## Example

The frontend framework can retrieve resolved style value of an Element as follows.

```jsx
// main-thread.js
let page = __CreateElement('page', 0, {});

let element = __CreateElement('view', 0, {});
__SetInlineStyles(element, {
  top: '10px',
  left: '10px',
  right: '10px',
  bottom: '10px',
});

__AppendElement(page, element);
__FlushElementTree(page, {});

let width = __GetComputedStyleByKey(element, 'width');
```

## Compatability

**Error:** No compatibility data found for `elements.get-computed-style-supported-properties`


---
url: /api/engine/element-api/__GetDataByKey.md
---

# `__GetDataByKey`

## Introduction

Returns the value of a specific data- attribute of an Element.

## Syntax

```jsx
__GetDataByKey(element: Element, key: string) : any;
```

### Parameters

|   Key   | Description                         |
| :-----: | ----------------------------------- |
| element | Any Element object.                 |
|   key   | data- key, a case-sensitive string. |

### Return Value

Returns the data- value corresponding to the data- key of the current Element, which can be of any type.

## Example

The frontend framework can retrieve the value of a data- attribute of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetDataset(element, { key: 'value' });

let dataset = __GetDataByKey(element, 'key');
```



---
url: /api/engine/element-api/__GetDataset.md
---

# `__GetDataset`

## Introduction

Returns all data- attributes of an Element node in the form of a map.

## Syntax

```jsx
__GetDataset(element: Element) : Record<string, any>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the dataset of the current Element as a map.

## Example

The frontend framework can retrieve the dataset of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetDataset(element, { key: 'value' });

let dataset = __GetDataset(element);
```



---
url: /api/engine/element-api/__GetElementConfig.md
---

# `__GetElementConfig`

## Introduction

Returns all configurations of an Element node in the form of a map.

## Syntax

```jsx
__GetElementConfig(element: Element) : Record<string, any>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the config of the current Element as a map.

## Example

The frontend framework can retrieve the config of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetConfig(element, { anyConfig: {} });

let listener = __GetElementConfig(element);
```



---
url: /api/engine/element-api/__GetElementUniqueID.md
---

# `__GetElementUniqueID`

## Introduction

Returns the unique ID of an Element.

## Syntax

```jsx
__GetElementUniqueID(element: Element) : number;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Currently, the return value is a unique ID of the Element object within the current LynxView, represented as a number.

## Example

The frontend framework can retrieve the unique ID of an Element as follows.

```jsx
let element = __CreateElement('view', 0, {});
let id = __GetElementUniqueID(element);
```



---
url: /api/engine/element-api/__GetEvent.md
---

# `__GetEvent`

## Introduction

Returns the event listener specific to the Element.

## Syntax

```jsx
__GetEvent(element: Element, name: string, type: string) : string|Function|undefined;
```

### Parameters

|   Key   | Description                                          |
| :-----: | ---------------------------------------------------- |
| element | Any Element object.                                  |
|   name  | A case-sensitive string representing the event name. |
|   type  | A case-sensitive string representing the event type. |

### Return Value

Returns the event listener for the current Element with the specified name.

## Example

The frontend framework can retrieve the event listener of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetEvents(element, [{ type: 'bindEvent', name: 'tap', function: 'onTap' }]);

let listener = __GetEvent(element, 'tap', 'bindEvent');
```



---
url: /api/engine/element-api/__GetEvents.md
---

# `__GetEvents`

## Introduction

Returns all event listeners of the Element in the form of an array.

## Syntax

```jsx
__GetEvents(element: Element) : Array<Record<string, any>>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns an array of all event listeners for the current Element, where each element in the array is a map that describes a single event listener.

## Example

The frontend framework can retrieve the event listeners of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetEvents(element, [{ type: 'bindEvent', name: 'tap', function: 'onTap' }]);

let listeners = __GetEvents(element);
```



---
url: /api/engine/element-api/__GetID.md
---

# `__GetID`

## Introduction

Returns the ID selector of the Element.

## Syntax

```jsx
__GetID(element: Element) : string;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

The ID selector of the current Element. If it has not been set, an empty string is returned.

## Example

The frontend framework can retrieve the Element ID selector as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetID(element, 'video');

let id = __GetID(element);
```



---
url: /api/engine/element-api/__GetInlineStyles.md
---

# `__GetInlineStyles`

## Introduction

Returns the inline styles of the Element.

## Syntax

```jsx
__GetInlineStyles(element: Element) : object;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the inline styles of the current Element in the form of a map.

## Example

The frontend framework can retrieve the inline styles of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetInlineStyles(element, 'top:10px;left:10px;right:10px;bottom:10px;');

let styles = __GetInlineStyles(element);
```



---
url: /api/engine/element-api/__GetParent.md
---

# `__GetParent`

## Introduction

Returns the parent node of the Element.

## Syntax

```jsx
__GetParent(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the parent node of the current node. If there is no parent node, it returns undefined.

## Example

The frontend framework can retrieve the parent node of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let parent = __GetParent(element);
```



---
url: /api/engine/element-api/__GetTag.md
---

# `__GetTag`

## Introduction

Returns the tag selector of the Element node.

## Syntax

```jsx
__GetTag(element: Element) : string;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

The return value is the tag selector of the Element object, with the type string.

## Example

The frontend framework can retrieve the tag selector of an Element as follows.

```jsx
let element = __CreateElement('view', 0, {});
let tag = __GetTag(element);
```



---
url: /api/engine/element-api/__InsertElementBefore.md
---

# `__InsertElementBefore`

## Introduction

Inserts an Element node into the specified parent node, before the reference node.

## Syntax

```jsx
__InsertElementBefore(parent: Element, child: Element, referenceNode: Element) : Element;
```

### Parameters

|      Key      | Description                                                                                                                                     |
| :-----------: | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|     parent    | The parent node object.                                                                                                                         |
|     child     | The child node to be inserted into the parent node.                                                                                             |
| referenceNode | The reference node before which the child node needs to be inserted. If the reference node is null, the child node will be inserted at the end. |

### Return Value

Returns the inserted child node.

## Example

The frontend framework can perform the insertion operation as follows.

```jsx
// main-thread.js
let first = __CreateElement('view', 0, {});

let last = __CreateElement('view', 0, {});

let mid = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, first);
__AppendElement(parent, last);

__InsertElementBefore(parent, mid, last);
```



---
url: /api/engine/element-api/__LastElement.md
---

# `__LastElement`

## Introduction

Returns the last child node of the Element.

## Syntax

```jsx
__LastElement(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the last child node of the current Element.

## Example

The frontend framework can retrieve the last child node of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let last = __LastElement(element);
```



---
url: /api/engine/element-api/__NextElement.md
---

# `__NextElement`

## Introduction

Returns the node that immediately follows the specified Element node in its parent's list of child nodes. If the specified node is the last node, it returns undefined.

## Syntax

```jsx
__NextElement(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the node that immediately follows the current Element object in its parent's list of child nodes. If the current Element is the last node, it returns undefined.

## Example

The frontend framework can retrieve the next node of a specified Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let next = __NextElement(element);
```



---
url: /api/engine/element-api/__RemoveElement.md
---

# `__RemoveElement`

## Introduction

Removes an Element node from its parent's list of child nodes.

## Syntax

```jsx
__RemoveElement(parent: Element, child: Element) : Element;
```

### Parameters

|   Key  | Description                                   |
| :----: | --------------------------------------------- |
| parent | The parent node object.                       |
|  child | The child node to be removed from the parent. |

### Return Value

Returns the removed child node.

## Example

The frontend framework can perform the removal operation as follows.

```jsx
// main-thread.js
let child = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, child);

__RemoveElement(parent, child);
```



---
url: /api/engine/element-api/__ReplaceElement.md
---

# `__ReplaceElement`

## Introduction

Replaces an Element node with a specified node.

## Syntax

```jsx
__ReplaceElement(newChild: Element, oldChild: Element) : void;
```

### Parameters

|    Key   | Description                                                                                                                                        |
| :------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| newChild | The new node that will replace the old node. If this node already exists in the Element tree, it will first be removed from its original position. |
| oldChild | The original node that is being replaced.                                                                                                          |

### Return Value

No return value.

## Example

The frontend framework can perform the replacement operation as follows.

```jsx
// main-thread.js
let newChild = __CreateElement('view', 0, {});

let oldChild = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, oldChild);

__ReplaceElement(newChild, oldChild);
```



---
url: /api/engine/element-api/__ReplaceElements.md
---

# `__ReplaceElements`

## Introduction

Replaces a list of Element nodes with a specified list of nodes.

## Syntax

```jsx
__ReplaceElements(parent: Element, newChildren: Array<Element>, oldChildren: Array<Element>) : void;
```

### Parameters

|     Key     | Description                                               |
| :---------: | --------------------------------------------------------- |
|    parent   | The parent node whose child nodes will be batch-replaced. |
| newChildren | The list of new nodes that will replace the old nodes.    |
| oldChildren | The list of original nodes that are being replaced.       |

### Return Value

No return value.

## Example

The frontend framework can perform the replacement operation as follows.

```jsx
// main-thread.js
let newChild = __CreateElement('view', 0, {});

let oldChild = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, oldChild);

__ReplaceElements(parent, [newChild], [oldChild]);
```



---
url: /api/engine/element-api/__SetAttribute.md
---

# `__SetAttribute`

## Introduction

Sets an attribute for a specific Element node.

## Syntax

```jsx
__SetAttribute(element: Element, key: string, value: any) : void;
```

### Parameters

|   Key   | Description                                           |
| :-----: | ----------------------------------------------------- |
| element | Any Element object.                                   |
|   key   | A string representing the attribute key to be set.    |
|  value  | Any value representing the attribute value to be set. |

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
```



---
url: /api/engine/element-api/__SetCSSId.md
---

# `__SetCSSId`

## Introduction

Sets a CSS ID for a specific Element node.

## Syntax

```jsx
__SetCSSId(element: Element, cssID: number) : void;
```

### Parameters

|   Key   | Description                          |
| :-----: | ------------------------------------ |
| element | Any Element object.                  |
|  cssID  | The CSS ID, which is of type number. |

### Return Value

No return value.

## Example

The frontend framework can perform replacement operations as follows.

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetCSSId(element, 0);
```



---
url: /api/engine/element-api/__SetClasses.md
---

# `__SetClasses`

## Introduction

Sets class selectors for a specific Element node.

## Syntax

```jsx
__SetClasses(element: Element, classNames: string) : void;
```

### Parameters

|     Key    | Description                                                                                       |
| :--------: | ------------------------------------------------------------------------------------------------- |
|   element  | Any Element object.                                                                               |
| classNames | A new list of class selectors, which will overwrite the existing class selectors, of type string. |

### Return Value

No return value.

## Example

The frontend framework can compile the corresponding frontend tags into render instructions as shown below.

```jsx
<view src="xxx" class="A B C" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__SetClasses(element, 'A B C');
```



---
url: /api/engine/element-api/__SetConfig.md
---

# `__SetConfig`

## Introduction

Sets a configuration for a specific Element node.

## Syntax

```jsx
__SetConfig(element: Element, config: Record<string, any>) : void;
```

### Parameters

|   Key   | Description                                                                |
| :-----: | -------------------------------------------------------------------------- |
| element | Any Element object.                                                        |
|  config | The configuration to be set for the Element object, which is a map object. |

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" bindtap="onTap" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetConfig(element, { anyConfig: {} });
```



---
url: /api/engine/element-api/__SetDataset.md
---

# `__SetDataset`

## Introduction

Sets data- attributes for a specific Element node.

## Syntax

```jsx
__SetDataset(element: Element, dataset: Record<string, any>) : void;
```

### Parameters

|   Key   | Description                                                          |
| :-----: | -------------------------------------------------------------------- |
| element | Any Element object.                                                  |
| dataset | The dataset to be set for the Element object, which is a map object. |

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" data-key="value" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetDataset(element, { key: 'value' });
```



---
url: /api/engine/element-api/__SetEvents.md
---

# `__SetEvents`

## Introduction

Sets event listeners for a specific Element node.

## Syntax

```jsx
__SetEvents(element: Element, listeners: Array<Record<string, any>>) : void;
```

### Parameters

|    Key    | Description                                                                                                                                                                 |
| :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  element  | Any Element object.                                                                                                                                                         |
| listeners | An array of listeners that describes the event listeners to add. Each element is a map that represents a specific event listener and must contain the following three keys: |

- type: A case-sensitive string representing the event type to listen for.
- name: A case-sensitive string representing the event name to listen for.
- function: The function can be a case-sensitive string or null/undefined.
  - When the function is a case-sensitive string, the Lynx SDK will send the current Element's parentComponentUniqueID, function, and event to the background thread to call the corresponding entry function when the event is triggered.
  - When the function is null or undefined, the Lynx SDK will remove the corresponding listener based on the type and name from the Element object's listeners.

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" bindtap="onTap" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetEvents(element, [{ type: 'bindEvent', name: 'tap', function: 'onTap' }]);
```



---
url: /api/engine/element-api/__SetID.md
---

# `__SetID`

## Introduction

Sets an ID selector for a specific Element node.

## Syntax

```jsx
__SetID(element: Element, id: string) : void;
```

### Parameters

|   Key   | Description                                                                       |
| :-----: | --------------------------------------------------------------------------------- |
| element | Any Element object.                                                               |
|    id   | The ID selector to be set for the Element object, which should be of type string. |

### Return Value

No return value.

## Example

The frontend framework can compile corresponding frontend tags into the following render instructions.

```jsx
<view id="video" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetID(element, 'video');
```



---
url: /api/engine/element-api/__SetInlineStyles.md
---

# `__SetInlineStyles`

## Introduction

Sets inline styles for a specific Element node.

## Syntax

```jsx
__SetInlineStyles(element: Element, value: string | object) : void;
```

### Parameters

|   Key   | Description                                                                   |
| :-----: | ----------------------------------------------------------------------------- |
| element | Any Element object.                                                           |
|  value  | Inline styles that override existing inline styles, of type string or object. |

### Return Value

No return value.

## Example

The frontend framework can compile corresponding frontend tags into the following render instructions.

```jsx
<view
  src="xxx"
  style={{ top: '10px', left: '10px', right: '10px', bottom: '10px' }}
/>
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetInlineStyles(element, {
  top: '10px',
  left: '10px',
  right: '10px',
  bottom: '10px',
});
```



---
url: /api/engine/element-api/__SwapElement.md
---

# `__SwapElement`

## Introduction

Swaps the positions of two Elements.

## Syntax

```jsx
__SwapElement(childA: Element, childB: Element) : void;
```

### Parameters

|   Key  | Description                       |
| :----: | --------------------------------- |
| childA | The first element to be swapped.  |
| childB | The second element to be swapped. |

### Return Value

No return value.

## Example

The frontend framework can perform replacement operations as follows.

```javascript
// main-thread.js
let childA = __CreateElement('view', 0, {});

let childB = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, childA);
__AppendElement(parent, childB);

__SwapElement(childA, childB);
```



---
url: /api/engine/element-api/__UpdateComponentID.md
---

# `__UpdateComponentID`

## Introduction

Updates the componentID of a ComponentElement.

## Syntax

```jsx
__UpdateComponentID(element: Element, componentID: string) : void;
```

### Parameters

|     Key     | Description                                                                                          |
| :---------: | ---------------------------------------------------------------------------------------------------- |
|   element   | Any ComponentElement.                                                                                |
| componentID | The componentID assigned to the ComponentElement by the frontend framework, which is case-sensitive. |

### Return Value

No return value.

## Example

The frontend framework can update the componentID of a ComponentElement as follows.

```javascript
// main-thread.js
let element = __CreateComponent(0, '1', 1, '', 'name', 'path', {}, {});

__UpdateComponentID(element, '2');
```



---
url: /api/errors/error-code.md
---

# Error Codes

| Error Code    | Description                                                |
| ------------- | ---------------------------------------------------------- |
| [102](#102)   | Error occurred while loading app bundle                    |
| [105](#105)   | Error occurred while reloading app bundle                  |
| [201](#201)   | Error occurred while executing background thread script    |
| [202](#202)   | Error occurred while calling JS function from platform     |
| [301](#301)   | Error occurred while loading image resource                |
| [302](#302)   | Error occurred while loading font resource                 |
| [303](#303)   | Error occurred while loading external resource             |
| [304](#304)   | Error occurred while loading i18n resource                 |
| [321](#321)   | Error occurred while invoking LynxResourceModule           |
| [398](#398)   | Custom error for resource                                  |
| [399](#399)   | Exception occurred while loading resource                  |
| [401](#401)   | Error occurred while updating data                         |
| [501](#501)   | Error occurred while invoking Element API                  |
| [502](#502)   | Error occurred while updating element                      |
| [601](#601)   | Internal layout error                                      |
| [602](#602)   | Performance issues related to layout                       |
| [603](#603)   | Failed to update layout                                    |
| [604](#604)   | Invalid usage or exceptions on ShadowNode                  |
| [901](#901)   | Common errors for invoking native modules                  |
| [998](#998)   | Error occurred in custom native modules                    |
| [999](#999)   | Exception occurred while invoking the native module        |
| [1099](#1099) | Exception occurred while handling event                    |
| [1101](#1101) | Error occurred while executing Main thread script          |
| [1111](#1111) | Error occurred while executing renderer function           |
| [1202](#1202) | Running on the wrong thread                                |
| [1301](#1301) | Generic CSS error                                          |
| [1302](#1302) | Error while manipulating ComputedCSSValue                  |
| [1303](#1303) | Error occurred while parsing CSS                           |
| [1601](#1601) | Failed to load a lazy bundle                               |
| [1901](#1901) | Error for main thread script call exception in worklet     |
| [1902](#1902) | Error for requestAnimationFrame call exception             |
| [1903](#1903) | Error for worklet module exception                         |
| [2001](#2001) | Error occurred while calling MTSBridge module              |
| [2201](#2201) | Error occurred while invoking component API                |
| [2202](#2202) | Error from List component                                  |
| [2203](#2203) | Error from Image component                                 |
| [2298](#2298) | Custom error of components                                 |
| [9901](#9901) | Platform exceptions                                        |
| [9902](#9902) | Exceptions encountered while calling Java native interface |

## 102: `EB_APP_BUNDLE_LOAD` \{#102}

### 10201: `E_APP_BUNDLE_LOAD_RENDER_FAILED`
 <Badge type="danger" text="Fatal" outline={true} />

Description: Failed to render app bundle
FixSuggestion: Should not call `loadTemplate` while the rendering pipeline of app bundle has not finished

### 10202: `E_APP_BUNDLE_LOAD_ENV_NOT_READY`
 <Badge type="danger" text="Fatal" outline={true} />

Description: `loadTemplate` while LynxEnv has not been initialized
FixSuggestion: Please call the initialization method of LynxEnv before loadTemplate

### 10203: `E_APP_BUNDLE_LOAD_BAD_RESPONSE`
 <Badge type="danger" text="Fatal" outline={true} />

Description: Failed to fetch app bundle by provider
FixSuggestion: Please check if the app bundle is available

### 10204: `E_APP_BUNDLE_LOAD_PARSE_FAILED`
 <Badge type="danger" text="Fatal" outline={true} />

Description: Failed to parse app bundle
FixSuggestion: Please check that 1. the provided bundle is an app bundle, 2. the engine version of the bundle is compatible with that of Lynx engine, 3. the bundle file is not broken

### 10205: `E_APP_BUNDLE_LOAD_BAD_BUNDLE`
 <Badge type="danger" text="Fatal" outline={true} />

Description: A bad TemplateBundle is provided
FixSuggestion: Please check the error message of the bundle

### 10299: `E_APP_BUNDLE_LOAD_EXCEPTION`
 <Badge type="danger" text="Fatal" outline={true} />

Description: Exception occurred while rendering app bundle

## 105: `EB_APP_BUNDLE_RELOAD` \{#105}

### 10501: `E_APP_BUNDLE_RELOAD_EARLY_RELOAD`
 <Badge type="danger" text="Error" outline={false} />

Description: `reloadTemplate` before `loadTemplate`
FixSuggestion: Please `loadTemplate` before `reloadTemplate`

## 201: `EB_BTS_RUNTIME_ERROR` \{#201}

### 20100: `E_BTS_RUNTIME_ERROR`
 <Badge type="info" text="Undecided" outline={false} />

Description: Runtime error for an unspecified reason

### 20101: `E_BTS_RUNTIME_ERROR_SCRIPT_ERROR`
 <Badge type="danger" text="Fatal" outline={true} />

Description: The script has syntax errors or other runtime errors
FixSuggestion: Please check the error message and fix the script

### 20102: `E_BTS_RUNTIME_ERROR_BYTECODE_SCRIPT_ERROR`
 <Badge type="danger" text="Fatal" outline={true} />

Description: The bytecode script has syntax errors or other runtime errors
FixSuggestion: Please check the error message and fix the script

### 20103: `E_BTS_RUNTIME_ERROR_BINDINGS_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: JavaScript binding API call errors
FixSuggestion: Please check the error message and fix binding API call

## 202: `EB_BTS_PLATFORM_CALL_JS_FUNCTION` \{#202}

### 20201: `E_BTS_PLATFORM_CALL_JS_FUNCTION_TOO_FREQUENCY`
 <Badge type="warning" text="Warn" outline={false} />

Description: Calling JS function too frequently. This may cause OOM issues
FixSuggestion: Please throttle related calls

## 301: `EB_RESOURCE_IMAGE` \{#301}

### 30101: `E_RESOURCE_IMAGE_BIG_IMAGE`
 <Badge type="danger" text="Error" outline={false} />

Description: The image bitmap size is too large relative to the UI.
FixSuggestion: Please resize the image to appropriate dimensions or enable downsampling

### 30102: `E_RESOURCE_IMAGE_PIC_SOURCE`
 <Badge type="danger" text="Error" outline={false} />

Description: Error occurred while decoding image
FixSuggestion: Possibly due to an unsupported image format or a corrupted file. Please verify the integrity of the image file

### 30103: `E_RESOURCE_IMAGE_FROM_USER_OR_DESIGN`
 <Badge type="danger" text="Error" outline={false} />

Description: Error from user actions or the network conditions
FixSuggestion: In most cases, the issue arises from a canceled image request or an unavailable network connection

### 30196: `E_RESOURCE_IMAGE_FROM_NETWORK_OR_OTHERS`
 <Badge type="danger" text="Error" outline={false} />

Description: Network or other issues
FixSuggestion: Please investigate the corresponding image download workflow for potential issues

### 30199: `E_RESOURCE_IMAGE_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: Exception occurred while loading image
FixSuggestion: An unidentified exception occurred that cannot be attributed to a specific cause. Please investigate further based on the available details

## 302: `EB_RESOURCE_FONT` \{#302}

### 30200: `E_RESOURCE_FONT`
 <Badge type="danger" text="Error" outline={false} />

Description: Failed to process font resource

### 30201: `E_RESOURCE_FONT_SRC_FORMAT_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Font src format error
FixSuggestion: Please check the font-face format

### 30202: `E_RESOURCE_FONT_RESOURCE_LOAD_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Failed to load font resource
FixSuggestion: Please check whether font resource is available

### 30203: `E_RESOURCE_FONT_BASE64_PARSING_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Failed to parse base64 resource
FixSuggestion: Please check whether the base64 resource is available

### 30204: `E_RESOURCE_FONT_FILE_FORMAT_NOT_SUPPORTED`
 <Badge type="danger" text="Error" outline={false} />

Description: Font file format is not supported
FixSuggestion: Please use a font file in ttf or otf format

### 30205: `E_RESOURCE_FONT_REGISTER_FAILED`
 <Badge type="info" text="Undecided" outline={false} />

Description: Failed to register font
FixSuggestion: If the font is displayed correctly, there is no need to deal with it

## 303: `EB_RESOURCE_EXTERNAL_RESOURCE` \{#303}

### 30301: `E_RESOURCE_EXTERNAL_RESOURCE_REQUEST_FAILED`
 <Badge type="danger" text="Error" outline={false} />

Description: Lynx resource fetcher requests failed
FixSuggestion: Please check whether the url of the external resource is available

### 30302: `E_RESOURCE_EXTERNAL_RESOURCE_LOCAL_RESOURCE_LOAD_FAIL`
 <Badge type="danger" text="Error" outline={false} />

Description: Failed to load local resource
FixSuggestion: Please check whether the local external resource is available

## 304: `EB_RESOURCE_I18N` \{#304}

### 30400: `E_RESOURCE_I18N`
 <Badge type="danger" text="Error" outline={false} />

Description: i18n Resource Error

## 321: `EB_RESOURCE_MODULE` \{#321}

### 32101: `E_RESOURCE_MODULE_PARAMS_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Parameter type mismatch or incorrect number of parameters while calling the requestResourcePrefetch or cancelResourcePrefetch API
FixSuggestion: Please refer to the parameter descriptions of this API in documentation and check the parameters used in the call

### 32102: `E_RESOURCE_MODULE_IMG_PREFETCH_HELPER_NOT_EXIST`
 <Badge type="danger" text="Error" outline={false} />

Description: Unable to access the image service because the app has not integrated LynxImageService
FixSuggestion: Please refer to the official documentation to integrate LynxImageService into your app

### 32103: `E_RESOURCE_MODULE_RESOURCE_SERVICE_NOT_EXIST`
 <Badge type="danger" text="Error" outline={false} />

Description: Unable to access resources because the app has not integrated the resource service
FixSuggestion: Please refer to the official documentation to implement the ILynxResourceService and integrate it into your app

## 398: `EB_RESOURCE_CUSTOM` \{#398}

### 39800: `E_RESOURCE_CUSTOM`
 <Badge type="danger" text="Error" outline={false} />

Description: Unexpected custom error
FixSuggestion: This is unexpected. Please file an issue to Lynx to help address it

## 399: `EB_RESOURCE_EXCEPTION` \{#399}

### 39900: `E_RESOURCE_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: Unexpect exception in loading resource
FixSuggestion: This is unexpected. Please file an issue to Lynx to help address it

## 401: `EB_DATA_FLOW_UPDATE` \{#401}

### 40101: `E_DATA_FLOW_UPDATE_INVALID_PROCESSOR`
 <Badge type="danger" text="Error" outline={false} />

Description: Call built-in function as data processor
FixSuggestion: Should not call `getDerivedStateFromProps`, `getDerivedStateFromError`, `shouldComponentUpdate` as data processor

### 40102: `E_DATA_FLOW_UPDATE_INVALID_TYPE`
 <Badge type="danger" text="Error" outline={false} />

Description: Invalid data type
FixSuggestion: Target string data should be enabled to be parsed into a table

### 40199: `E_DATA_FLOW_UPDATE_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: Exception occurred while updating data

## 501: `EB_ELEMENT_API` \{#501}

### 50101: `E_ELEMENT_API_FATAL`
 <Badge type="danger" text="Fatal" outline={true} />

Description: Fatal error in element API. Please find detailed information in the context

### 50102: `E_ELEMENT_API_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Error in element API. Please find detailed information in the context

## 502: `EB_ELEMENT_UPDATE` \{#502}

### 50201: `E_ELEMENT_UPDATE_NODE_IS_NULL`
 <Badge type="danger" text="Fatal" outline={true} />

Description: Element update error for an unspecified reason

## 601: `EB_LAYOUT_INTERNAL` \{#601}

### 60100: `E_LAYOUT_INTERNAL`
 <Badge type="danger" text="Error" outline={false} />

Description: Cannot find ShadowNode
FixSuggestion: Lynx internal error. Please check whether the creating of corresponding ShadowNode failed

## 602: `EB_LAYOUT_PERF` \{#602}

### 60201: `E_LAYOUT_PERF_INFINITE_LOOP`
 <Badge type="danger" text="Error" outline={false} />

Description: Infinite Loop of layout is detected
FixSuggestion: Infinite loop of layout happens. It usually happens when the front-end decides the content size based on the viewport size, while the client is deciding the viewport size based on the content size

## 603: `EB_LAYOUT_UPDATE` \{#603}

### 60301: `E_LAYOUT_UPDATE_UI_NOT_FOUND`
 <Badge type="danger" text="Error" outline={false} />

Description: Can not find UI while updating layout
FixSuggestion: This is an internal error of Lynx. LynxUI has not been created or the creation failed while updating

## 604: `EB_LAYOUT_PLATFORM` \{#604}

### 60401: `E_LAYOUT_PLATFORM_NODE_NULL`
 <Badge type="danger" text="Error" outline={false} />

Description: ShadowNode is accessed after destroyed
FixSuggestion: This is an internal error of Lynx, which usually occurs when multiple threads access ShadowNode at the same time

## 901: `EB_NATIVE_MODULES_COMMON` \{#901}

### 90101: `E_NATIVE_MODULES_COMMON_MODULE_NOT_FOUND`
 <Badge type="danger" text="Error" outline={false} />

Description: Native module not found
FixSuggestion: Please verify that the invoked native module name matches the registered name and confirm module registration status

### 90102: `E_NATIVE_MODULES_COMMON_FUNCTION_NOT_FOUND`
 <Badge type="danger" text="Error" outline={false} />

Description: Native module method not found
FixSuggestion: Please verify proper method registration using platform-specific annotations on Android or static method declarations on iOS (For details, refer to the native module documentation). Additionally, ensure that the invoked method name exactly matches the registered name in the native module implementation

### 90103: `E_NATIVE_MODULES_COMMON_WRONG_PARAM_NUM`
 <Badge type="danger" text="Error" outline={false} />

Description: Parameter count mismatch in native module method invocation
FixSuggestion: Please ensure that the number of parameters passed to the native method exactly matches the declared parameters in the native module implementation

### 90104: `E_NATIVE_MODULES_COMMON_WRONG_PARAM_TYPE`
 <Badge type="danger" text="Error" outline={false} />

Description: Parameter type mismatch in native module method invocation
FixSuggestion: Please verify that the parameter types in the method call exactly match the native module implementation. Ensure type compatibility across all parameters and validate the parameter order corresponds to the native method signature. You can check the native module documentation for expected data types

### 90105: `E_NATIVE_MODULES_COMMON_AUTHORIZATION_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Does not have permission to call the method
FixSuggestion: Please file an issue to Lynx to help address it

### 90106: `E_NATIVE_MODULES_COMMON_SYSTEM_AUTHORIZATION_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Does not have permission to call the method
FixSuggestion: Please file an issue to Lynx to help address it

### 90107: `E_NATIVE_MODULES_COMMON_RETURN_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: The value returned by module method is invalid
FixSuggestion: Please file an issue to Lynx to help address it

## 998: `EB_NATIVE_MODULES_CUSTOM_ERROR` \{#998}

### 99800: `E_NATIVE_MODULES_CUSTOM_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Custom error reported from native module
FixSuggestion: This error is explicitly defined by the native module implementation. Please refer to the module error handling guide or contact the module maintainer with complete error context

## 999: `EB_NATIVE_MODULES_EXCEPTION` \{#999}

### 99900: `E_NATIVE_MODULES_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: Internal exception in native module method execution
FixSuggestion: This error indicates an unhandled runtime exception within the native module implementation. Please refer to the module error handling guide or contact the module maintainer with complete error context

## 1099: `EB_EVENT_EXCEPTION` \{#1099}

### 109900: `E_EVENT_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: An exception occurred during LynxView dispatchTouchEvent
FixSuggestion: This error is caught by the Lynx Engine. Please file an issue to Lynx to help address it

## 1101: `EB_MTS_RUNTIME_ERROR` \{#1101}

### 110100: `E_MTS_RUNTIME_ERROR`
 <Badge type="info" text="Undecided" outline={false} />

Description: Main thread script error for an unspecified reason

## 1111: `EB_MTS_RENDERER_FUNCTION` \{#1111}

### 111101: `E_MTS_RENDERER_FUNCTION_FATAL`
 <Badge type="danger" text="Fatal" outline={true} />

Description: Fatal error during rendering. Please find detailed information in the context

### 111102: `E_MTS_RENDERER_FUNCTION_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Fatal error during rendering. Please find detailed information in the context

## 1202: `EB_THREAD_WRONG_THREAD` \{#1202}

### 120201: `E_THREAD_WRONG_THREAD_DESTROY_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Please ensure that `destroy` is called on UI thread

### 120202: `E_THREAD_WRONG_THREAD_SYNC_FLUSH_ERROR`
 <Badge type="danger" text="Error" outline={false} />

Description: Please ensure that `SyncFlush` is called on UI thread

## 1301: `EB_CSS` \{#1301}

### 130100: `E_CSS`
 <Badge type="info" text="Undecided" outline={false} />

Description: CSS error for an unspecified reason

### 130101: `E_CSS_UNKNOWN_PROPERTY`
 <Badge type="info" text="Undecided" outline={false} />

Description: Unknown CSS property id

### 130102: `E_CSS_UNSUPPORTED_VALUE`
 <Badge type="info" text="Undecided" outline={false} />

Description: Unsupported CSS value
FixSuggestion: Please check your value for the property follow the detailed message

## 1302: `EB_CSS_COMPUTED_CSS_VALUE` \{#1302}

### 130201: `E_CSS_COMPUTED_CSS_VALUE_UNKNOWN_SETTER`
 <Badge type="danger" text="Error" outline={false} />

Description: Error occurred while setting value to ComputedCSSValue
FixSuggestion: Ignore it or raise an issue on github to let us know. This error is unexpected, which might be caused by internal pipeline fault

### 130202: `E_CSS_COMPUTED_CSS_VALUE_UNKNOWN_GETTER`
 <Badge type="danger" text="Error" outline={false} />

Description: Error occurred while getting value from ComputedCSSValue
FixSuggestion: Ignore it or raise an issue on github to let us know. This error is unexpected, which might be caused by internal pipeline fault

### 130203: `E_CSS_COMPUTED_CSS_VALUE_UNSUPPORTED_INHERITANCE`
 <Badge type="danger" text="Error" outline={false} />

Description: Property is not inheritable
FixSuggestion: Remove property name from inheritance list

## 1303: `EB_CSS_PARSER` \{#1303}

### 130300: `E_CSS_PARSER`
 <Badge type="danger" text="Error" outline={false} />

Description: Generic error while parsing CSS value. Value is not acceptable for the property
FixSuggestion: Please use values following the property definitions. You can get the definitions at the official website

## 1601: `EB_LAZY_BUNDLE_LOAD` \{#1601}

### 160101: `E_LAZY_BUNDLE_LOAD_BAD_RESPONSE`
 <Badge type="danger" text="Error" outline={false} />

Description: Lazy bundle request returned with bad response
FixSuggestion: Please check whether the url of the lazy bundle is available

### 160102: `E_LAZY_BUNDLE_LOAD_EMPTY_FILE`
 <Badge type="danger" text="Error" outline={false} />

Description: The binary data of lazy bundle is empty
FixSuggestion: Please check whether the lazy bundle file is empty

### 160103: `E_LAZY_BUNDLE_LOAD_DECODE_FAILED`
 <Badge type="danger" text="Error" outline={false} />

Description: Failed to decode lazy bundle binary data
FixSuggestion: Please check whether the lazy bundle file is broken or it is compatible with the host page

### 160104: `E_LAZY_BUNDLE_LOAD_BAD_BUNDLE`
 <Badge type="danger" text="Error" outline={false} />

Description: A bad lazy bundle is provided
FixSuggestion: Please check the error message of the bundle

## 1901: `EB_WORKLET_MTS_CALL_EXCEPTION` \{#1901}

### 190100: `E_WORKLET_MTS_CALL_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: Please check the worklet function is callable, and the worklet file is imported correctly

## 1902: `EB_WORKLET_RAF_CALL_EXCEPTION` \{#1902}

### 190200: `E_WORKLET_RAF_CALL_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: Error for calling requestAnimationFrame
FixSuggestion: Calling requestAnimationFrame failed. This is usually caused by an error in the callback function. Please ensure that the callback function executes without errors

## 1903: `EB_WORKLET_MODULE_EXCEPTION` \{#1903}

### 190300: `E_WORKLET_MODULE_EXCEPTION`
 <Badge type="danger" text="Error" outline={false} />

Description: Can not find worklet module
FixSuggestion: Make sure you have imported worklet file correctly

## 2001: `EB_MTS_BRIDGE_MODULE` \{#2001}

### 200101: `E_MTS_BRIDGE_MODULE_WRONG_PARAM`
 <Badge type="danger" text="Error" outline={false} />

Description: Invoke function with wrong parameter

## 2201: `EB_COMPONENT_API` \{#2201}

### 220101: `E_COMPONENT_API_DEPRECATED`
 <Badge type="danger" text="Error" outline={false} />

Description: A deprecated component API is invoked

## 2202: `EB_COMPONENT_LIST` \{#2202}

### 220201: `E_COMPONENT_LIST_ILLEGAL_ITEM_KEY`
 <Badge type="danger" text="Error" outline={false} />

Description: Error for illegal list item-key
FixSuggestion: Please check the legality of the item-key

### 220202: `E_COMPONENT_LIST_DUPLICATED_CELL`
 <Badge type="danger" text="Error" outline={false} />

Description: List has duplicated cell in cache
FixSuggestion: We have encountered a system-level error. Please file an issue to Lynx to help resolve this problem

### 220203: `E_COMPONENT_LIST_CELL_NOT_FOUND`
 <Badge type="danger" text="Error" outline={false} />

Description: List cell not found in cache
FixSuggestion: We have encountered a system-level error. Please file an issue to Lynx to help resolve this problem

### 220204: `E_COMPONENT_LIST_DYNAMIC_CHANGE_ORIENTATION`
 <Badge type="danger" text="Error" outline={false} />

Description: List does not support changing orientation dynamically
FixSuggestion: Please do not change the value of `vertical-orientation` dynamically

### 220205: `E_COMPONENT_LIST_INVALID_PROPS_ARG`
 <Badge type="danger" text="Error" outline={false} />

Description: There is an invalid parameter set in some props
FixSuggestion: For parameter usage, please check documentation of list component

### 220206: `E_COMPONENT_LIST_CHILD_COMPONENT_NOT_EXIST`
 <Badge type="danger" text="Error" outline={false} />

Description: Child component of list does not exist
FixSuggestion: The internal state of the engine has become inconsistent. Please file an issue to Lynx for help resolving this problem

### 220207: `E_COMPONENT_LIST_UNSUPPORTED_THREAD_STRATEGY`
 <Badge type="danger" text="Error" outline={false} />

Description: Multi thread strategy can not be used by default
FixSuggestion: Please set the attribute enable-async-list of <list />
 to true
### 220208: `E_COMPONENT_LIST_DUPLICATE_ITEM_KEY`
 <Badge type="danger" text="Error" outline={false} />

Description: Error for duplicate list item-key
FixSuggestion: Please check the legality of the item-key

## 2203: `EB_COMPONENT_IMAGE` \{#2203}

### 220301: `E_COMPONENT_IMAGE_UNSUPPORTED_PROP`
 <Badge type="danger" text="Error" outline={false} />

Description: Failed to apply blur-radius on \<image> element, meaning that the effect will not be visible on this platform
FixSuggestion: This may be due to platform-specific limitations or system restrictions. If blur-radius is not supported on this platform, consider using CSS filter: blur() as an alternative

## 2298: `EB_COMPONENT_CUSTOM` \{#2298}

### 229800: `E_COMPONENT_CUSTOM`
 <Badge type="danger" text="Error" outline={false} />

Description: An error occurs in an customized element

## 9901: `EB_EXCEPTION_PLATFORM` \{#9901}

### 990100: `E_EXCEPTION_PLATFORM`
 <Badge type="danger" text="Error" outline={false} />

Description: Platform exceptions for an unspecified reason
FixSuggestion: This error is caught by Lynx engine. Please file an issue to Lynx for help

## 9902: `EB_EXCEPTION_JNI` \{#9902}

### 990200: `E_EXCEPTION_JNI`
 <Badge type="danger" text="Error" outline={false} />

Description: JNI exceptions for an unspecified reason
FixSuggestion: This error is caught by Lynx engine. Please file an issue to Lynx for help



---
url: /api/errors/lynx-error.md
---

# LynxError API

<APISummary />

`LynxError` is the standard error object returned by the Lynx runtime to indicate runtime failures, warnings, or recoverable issues in your app.

It contains both **machine-readable information** (error code, subcode, severity level) and a **human-readable message** to help with debugging and recovery.

## Use Cases

- Display meaningful errors in debug or development mode
- Trigger fallback UI or navigation for fatal runtime issues
- Report errors for analytics or bug tracking

***

## Core Concepts

### Error Code

A **3–4 digit number** identifying the category or behavior of an error.
For example, `301` represents an image loading error.

Refer to the [Error Codes documentation](/api/errors/error-code.md) for a full list of codes and their meanings.

### Subcode

A **5–6 digit number** derived from the error code, used to specify the exact cause of the error.
For example, `30101` indicates that the loaded image is too large.

Refer to the [Error Codes documentation](/api/errors/error-code.md) for details on individual subcodes.

### Level

`LynxError` defines four levels: `Fatal`, `Error`, `Warn`, and `Undecided`.

| Level       | Meaning                | Suggested Action             |
| ----------- | ---------------------- | ---------------------------- |
| `Fatal`     | App is likely unusable | Reload or fallback UI        |
| `Error`     | Recoverable issue      | Log and retry                |
| `Warn`      | Non-blocking warning   | Log and continue             |
| `Undecided` | Not yet categorized    | Handle gracefully, log issue |

### Message

A JSON-formatted string containing detailed error information, including:

- `code`
- `subcode`
- `level`
- `message`
- `suggestion` (optional)

***

## Platform Methods

### Android

| Method           | Return Type | Description            |
| ---------------- | ----------- | ---------------------- |
| `getErrorCode()` | `int`       | Returns the error code |
| `getSubCode()`   | `int`       | Returns the subcode    |
| `getLevel()`     | `String`    | Returns the level      |
| `getMsg()`       | `String`    | Returns the message    |

### iOS

| Property / Method | Type            | Description                                                                                       |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------- |
| `errorCode`       | `NSInteger`     | Returns the error code                                                                            |
| `subcode`         | `NSInteger`     | Returns the subcode                                                                               |
| `level`           | `NSString*`     | Returns the level                                                                                 |
| `userInfo()`      | `NSDictionary*` | Returns a dictionary where the message can be queried using the key `LynxErrorUserInfoKeyMessage` |

### HarmonyOS

| Method           | Type             | Description            |
| ---------------- | ---------------- | ---------------------- |
| `getErrorCode()` | `number`         | Returns the error code |
| `getSubCode()`   | `number`         | Returns the subcode    |
| `getLevel()`     | `LynxErrorLevel` | Returns the level      |
| `getMsg()`       | `string`         | Returns the message    |

***

## Example

### JavaScript

```js
lynx.onError((err) => {
  if (err.getLevel() === 'Fatal') {
    // Possibly reload or fallback to home
    console.error('Critical error occurred:', err.getMsg());
  }
});
```

### Kotlin

```kotlin
fun onLynxError(error: LynxError) {
  if (error.level == "Fatal") {
    println("Fatal error: ${error.msg}")
  }
}
```

### Swift

```swift
func onLynxError(_ error: LynxError) {
  if error.level == "Fatal" {
    print("Fatal error: \(error.msg)")
  }
}
```

### ETS

```ts
onLynxError(error: LynxError) {
  if (error.level == LynxErrorLevel.Fatal) {
    console.error('Fatal error:', error.getMsg());
  }
}
```

***

## Compatibility

**Compatibility Table**
**Query:** `errors.lynx-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.4 | - |

**Description:** Structure used to represent an error




---
url: /api/index.md
---




---
url: /api/lynx-api/event/animation-event.md
---

# AnimationEvent

<APISummary />

Represents the animation event object, inherited from [CustomEvent](/api/lynx-api/event/custom-event.md), used to describe the state changes of the animation in its life cycle, such as start, end, etc.

The event object contains information such as the type and name of the animation.

## Instance property

### detail

```ts
detail: {
  animation_type: string,
  animation_name: string,
  new_animator: boolean,
}
```

Represents some basic information of the animation to which the event belongs.

- `animation-type`: The type of the animation. If it is a keyframe animation, this value is `keyframe-animation`; if it is a transition animation, this value is `transition-animation`.
- `animation-name`: The name of the animation. If it is a keyframe animation, it is the name of [`@keyframes`](/api/css/at-rule/keyframes.md) in CSS; if it is a transition animation, it is the name of [`transition-property`](/api/css/properties/transition-property.md) in CSS.
- `new_animator`: The default value is `true`.

## AnimationEvent type

:::info
During the animation execution process, if the animation node is uninstalled and destroyed, the [`animationcancel`](#animationcancel) and [`transitioncancel`](#transitioncancel) events on the node will not be triggered.
:::

### animationstart

Indicates the start of keyframe animation playback.

### animationend

Indicates the end of keyframe animation playback.

### animationcancel

Indicates that the keyframe animation playback is canceled.

### animationiteration

Indicates the number of keyframe animation playback iterations.

### transitionstart

Indicates the start of the transition animation playback.

### transitionend

Indicates the end of the transition animation playback.

### transitioncancel

Indicates that the transition animation playback is canceled.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.AnimationEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.6 | - |
| iOS | 2.6 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/custom-event.md
---

# CustomEvent

<APISummary />

Represents a custom event object, inherited from [`Event`](/api/lynx-api/event/event.md), used to describe the state changes of the component customization, such as [`scroll`](/api/elements/built-in/scroll-view.md#bindscroll).

This event object contains some state information of the component customization, and developers can use it to understand the state changes of the component.

## Instance property

:::info
There are two properties of the custom event object, one is [`params`](#params), the other is [`detail`](#detail). [`params`](#params) will be discarded in the future, and it is recommended to use [`detail`](#detail).
:::

### params

```ts
params: object;
```

Represents some state information of the component customization.

### detail

```ts
detail: object;
```

Represents some state information of the component customization.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.CustomEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/event.md
---

# Event

<APISummary />

`Event` represents the event object when the event is triggered, which contains the state information when the event is triggered. Developers can listen through the [Event Handler Property](/guide/interaction/event-handling/event-propagation.md#event-handler-property).

Lynx has many different types of event objects, all of which are directly or indirectly inherited from `Event`. `Event` itself contains properties and methods applicable to all event objects.

## `Event` type

[`TouchEvent`](/api/lynx-api/event/touch-event.md)

`TouchEvent` represents a touch event object, which describes the state change of a finger on a touch surface (such as a touch screen).

[`CustomEvent`](/api/lynx-api/event/custom-event.md)

`CustomEvent` represents a custom event object, which describes the state change of a custom component.

[`AnimationEvent`](/api/lynx-api/event/animation-event.md)

`AnimationEvent` represents an animation event object, describing the state changes of the CSS animation life cycle.

## Instance property

### type

```ts
type: string;
```

Indicates the type of event.

### timestamp

```ts
timestamp: number;
```

Indicates the timestamp when the event was generated.

### target

```ts
target: {
  id: string,
  uid: number,
  dataset: [key: string]: any,
}
```

Indicates a collection of some attribute values ​​of `element` that triggered the event.

- `id`: `element`'s `id` selector.
- `uid`: `element`'s unique identifier in Lynx Engine.
- `dataset`: A collection of custom attributes starting with [`data-`](/api/elements/built-in/view.md#data-) on `element`.

### currentTarget

```ts
currentTarget: {
  id: string,
  uid: number,
  dataset: [key: string]: any,
}
```

A collection of attribute values ​​of `element` that listens to events.

- `id`: `element`'s `id` selector.
- `uid`: `element`'s unique identifier in Lynx Engine.
- `dataset`: A collection of custom attributes starting with [`data-`](/api/elements/built-in/view.md#data-) on `element`.

## Instance method

### stopPropagation <RuntimeBadge type="mts" />

```ts
stopPropagation(): void;
```

Stop bubbling and prevent the event from continuing to bubble up the touch response chain.

Calling it in the [main thread script](/react/main-thread-script.md) can affect both event bubbling and event handler triggering in `JS`.

**This is an example below:  event**

**Entry:** `src/event_stop_propagation`
**Bundle:** `dist/event_stop_propagation.lynx.bundle` | Web: `dist/event_stop_propagation.web.bundle`

```tsx {34}
import { root, runOnBackground, useState } from "@lynx-js/react";
import "./index.css";
import type { MainThread } from "@lynx-js/types";

export default function App() {
  const [active, setActive] = useState({ outer: false, middle: false, inner: false });

  // Utility to flash a box when it's clicked
  const flashBT = (key: "outer" | "middle" | "inner") => {
    setActive((prev) => ({ ...prev, [key]: true }));
    setTimeout(() => setActive((prev) => ({ ...prev, [key]: false })), 200);
  };

  // Utility to flash a box when it's clicked
  const flash = (
    key: "outer" | "middle" | "inner",
  ) => {
    "main thread";
    runOnBackground(flashBT)(key);
  };

  function handleOuterTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("outer");
  }

  function handleMiddleTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("middle");
  }

  function handleInnerTap(e: MainThread.TouchEvent) {
    "main thread";
    e.stopPropagation(); // ✋ stop event bubbling
    flash("inner");
  }

  return (
    <view
      main-thread:bindtap={handleOuterTap}
      className={`box outer ${active.outer ? "active" : ""}`}
    >
      <text>Outer {active.outer ? "(active)" : "(inactive)"}</text>
      <view
        main-thread:bindtap={handleMiddleTap}
        className={`box middle ${active.middle ? "active" : ""}`}
      >
        <text>Middle {active.middle ? "(active)" : "(inactive)"}</text>
        <view
          main-thread:bindtap={handleInnerTap}
          className={`box inner ${active.inner ? "active" : ""}`}
        >
          <text>Inner (click me, stops propagation) {active.inner ? "(active)" : "(inactive)"}</text>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



s

### stopImmediatePropagation <RuntimeBadge type="mts" />

```ts
stopImmediatePropagation(): void;
```

Stop bubbling, prevent the event from continuing to bubble in the event response chain, and prevent other event handlers of the same event on the current node from being triggered.

Calling it in the [main thread script](/react/main-thread-script.md) can affect both event bubbling and event handler triggering in `JS`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.Event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/global-event.md
---

# GlobalEvent

<APISummary />

Represents a global event object, which is an array that can be passed between different elements and components, or between the client and the front end.

Developers can listen to this event based on [`GlobalEventEmitter`](/guide/interaction/event-handling/event-propagation.md#globaleventemitter).

## GlobalEvent Type

### keyboardstatuschanged

Represents the keyboard status change caused by input method focus or user operation.

```json
[
  status: ['on', 'off'],    // indicates the status of the keyboard
  height: number,           // indicates the height of the keyboard, in px
  compatHeight: number,     // indicates the height of compatible keyboards, in px
]
```

### onWindowResize

Indicates the change in Lynx page size due to screen rotation or external typesetting.

```json
[
  width?: ['on', 'off'],    // indicates the width of the Lynx page after the change, in px
  height?: number,          // indicates the height of the Lynx page after the change, in px
]
```

### exposure

Indicates that a node in the exposure data source has generated exposure, that is, the visibility of the node has changed from invisible to visible.

```json
[
  {
    "exposure-id": string,      // exposure-id set on the target node
    "exposure-scene": string,   // exposure-scene set on the target node
    "sign": string,             // uid of the target node
    "dataset": object,          // "data-" field set on the target node
    //......
  },
  //......
]
```

### disexposure

Indicates that a node in the exposure data source has generated a reverse exposure, that is, the visibility of the node has changed from visible to invisible.

```json
[
  {
    "exposure-id": string,      // exposure-id set on the target node
    "exposure-scene": string,   // exposure-scene set on the target node
    "sign": string,             // uid of the target node
    "dataset": object,          // "data-" field set on the target node
    //......
  },
  //......
]
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.GlobalEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/mouse-event.md
---

# MouseEvent

<APISummary />

Represents a mouse event, inherited from [`Event`](/api/lynx-api/event/event.md), which is a type of event that describes the user's interaction with the mouse. For example, mouse click.

## Instance property

### button

```ts
button: number;
```

When a mouse event is triggered, if any mouse button is pressed or released, a integer value representing this mouse button will be returned.

| Value | Description            |
| ----- | ---------------------- |
| 1     | primary mouse button   |
| 2     | secondary mouse button |
| 3     | middle mouse button    |

### buttons

```ts
buttons: number;
```

When a mouse event is triggered, if any buttons are pressed, a integer value representing multiple buttons which user is pressing will be returned. Each button occupies one bit field.

| Bit | Description            |
| --- | ---------------------- |
| 0   | primary mouse button   |
| 1   | secondary mouse button |
| 2   | middle mouse button    |

### x

```ts
x: number;
```

Represents the horizontal axis position of the mouse pointer in the `element` coordinate system that contains the mouse pointer and is closest to the user.

### y

```ts
y: number;
```

Represents the vertical axis position of the mouse pointer in the `element` coordinate system that contains the mouse pointer and is closest to the user.

### pageX

```ts
pageX: number;
```

Indicates the horizontal axis position of the mouse pointer in the current `LynxView` coordinate system.

### pageY

```ts
pageY: number;
```

Represents the vertical axis position of the mouse pointer in the current `LynxView` coordinate system.

### clientX

```ts
clientX: number;
```

Indicates the horizontal axis position of the mouse pointer in the current window coordinate system.

### clientY

```ts
clientY: number;
```

Indicates the vertical axis position of the mouse pointer in the current window coordinate system.

## Type of MouseEvent

### mousedown

Indicates a mouse button is pressed (primary or secondary). [`target`](/api/lynx-api/event/event.md#target) is the `element` closest to the user that contains the mouse pointer.

### mousemove

Indicates that the mouse moves after [`mousedown`](#mousedown). [`target`](/api/lynx-api/event/event.md#target) is always the same as [`mousedown`](#mousedown)'s [`target`](/api/lynx-api/event/event.md#target).

### mouseup

Indicates that the mouse button is released, [`target`](/api/lynx-api/event/event.md#target) is the same as [`mousedown`](#mousedown)'s [`target`](/api/lynx-api/event/event.md#target).

### mouseenter

Indicates that the mouse moves into the activation area of [`target`](/api/lynx-api/event/event.md#target) for the first time. [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the mouse pointer and is closest to the user.

Note: the `mouseenter` event does not bubble, and it can't be captured by using [`capture-`](/guide/interaction/event-handling/event-propagation.md#event-handler-property) API.

### mouseover

Indicates that the mouse is moving inside [`target`](/api/lynx-api/event/event.md#target) after [`mouseenter`](#mouseenter). [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the mouse pointer and is closest to the user.

### mouseleave

Indicates that the mouse moves out of the activation area of [`target`](/api/lynx-api/event/event.md#target) for the first time. [`target`](/api/lynx-api/event/event.md#target) is the same as previous [`mouseenter`](#mouseenter)'s [`target`](/api/lynx-api/event/event.md#target).

Note: the `mouseleave` event does not bubble, and it can't be captured by using [`capture-`](/guide/interaction/event-handling/event-propagation.md#event-handler-property) API.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.MouseEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/touch-event.md
---

# TouchEvent

<APISummary />

Represents a touch event object, inherited from [`Event`](/api/lynx-api/event/event.md), used to describe the state changes of a finger on a touch surface (such as a touch screen), such as finger movement, click, long press, etc.

This event object contains one or more touch points, through which developers can understand the state changes of fingers on the touch surface.

## Instance property

### detail

```ts
detail: {
  x: number,
  y: number,
}
```

Represents the touch point position of the first finger.

- `x`: The horizontal axis position of the touch point in the current `LynxView` coordinate system.
- `y`: The vertical axis position of the touch point in the current `LynxView` coordinate system.

### touches

```ts
touches: Touch []
```

Represents the `Touch` object currently on the touch plane. Each `Touch` object describes the touch point information of the corresponding finger. The format is as follows:

```ts
{
  identifier: number,   // Unique identifier of the touch point, which remains unchanged during the same touch process
  x: number,            // The horizontal position of the touch point in the coordinate system of the element actually touched
  y: number,            // The vertical position of the touch point in the coordinate system of the element actually touched
  pageX: number,        // The horizontal position of the touch point in the current LynxView coordinate system
  pageY: number,        // The vertical position of the touch point in the current LynxView coordinate system
  clientX: number,      // The horizontal position of the touch point in the current window coordinate system
  clientY: number,      // The horizontal position of the touch point in the current window coordinate system
}
```

### changedTouches

```ts
changedTouches: Touch []
```

Indicates a `Touch` object whose state has changed compared to the last touch event, such as from nothing to something, position change, from something to nothing. The format of [`changesTouches`](#changedtouches) is the same as that of [`touches`](#touches).

## TouchEvent type

### touchstart

Indicates that the finger begins to touch the touch surface. [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the touch point and is closest to the user.

### touchmove

Indicates that the finger moves on the touch surface. [`target`](/api/lynx-api/event/event.md#target) is always the same as [`target`](/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart).

### touchend

Indicates that the finger leaves the touch surface. [`target`](/api/lynx-api/event/event.md#target) is the same as [`target`](/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart). The touch point that has left the screen can be found in [`changedTouches`](#changedtouches).

### touchcancel

Indicates that the touch event is interrupted by the system or `Lynx` external gesture, such as system pop-up window or incoming call. [`target`](/api/lynx-api/event/event.md#target) is the same as [`target`](/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart). The interrupted touch point can be found in [`changedTouches`](#changedtouches).

### tap

This indicates a single tap on the touch surface. The [`target`](/api/lynx-api/event/event.md#target) is the `element` containing the touch point and closest to the user. Only the first finger can trigger this event.

If the finger moves beyond a certain distance threshold, or if an `element` in the [`event response chain`](/guide/interaction/event-handling/event-propagation.md#event-response-chain) slides, the `tap` event will not trigger.

This event and the [`longpress`](#longpress) event are mutually exclusive in event listening. That is, if the front-end listens for both events simultaneously, they will not trigger concurrently; [`longpress`](#longpress) takes precedence.

### longpress

This indicates a long press on the touch surface. The [`target`](/api/lynx-api/event/event.md#target) is the `element` containing the touch point and closest to the user. Only the first finger can trigger this event. The `longpress` event will not trigger if the finger moves beyond a certain threshold or the long press time interval is less than `500 ms`.

### click

This indicates a single click on the touch plane. [`target`](/api/lynx-api/event/event.md#target) is the `element` containing the touch point, closest to the user, and listening for the `click` event. Only the first finger can trigger this event.

This event differs slightly from the [`tap`](#tap) event, primarily in its blocking distance threshold and the [`target`](/api/lynx-api/event/event.md#target):

- The [`target`](/api/lynx-api/event/event.md#target) for [`tap`](#tap) event is the node closest to the user during the actual touch; while the [`target`](/api/lynx-api/event/event.md#target) for `click` event is the node closest to the user that is listening for the `click` event.

- The blocking distance threshold for [`tap`](#tap) event is fixed; it won't trigger if the finger moves beyond a certain distance. The blocking distance threshold for `click` event depends on the touch hotspot of [`target`](/api/lynx-api/event/event.md#target); it won't trigger if the finger moves outside the touch hotspot.

- When an element slides on the [`event response chain`](/guide/interaction/event-handling/event-propagation.md#event-response-chain) corresponding to [`target`](/api/lynx-api/event/event.md#target), the [`tap`](#tap) or `click` event cannot be triggered.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/tap_and_click.png" width="100%" height="100%" />

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.TouchEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/global.md
---




---
url: /api/lynx-api/global/clear-interval.md
---

# clearInterval() global function

<APISummary />

Cancels the timer set by `setInterval`.

## Syntax

```typescript
clearInterval(timerId: number): void;
```

### Parameters

#### timerId

The timer ID returned by `setInterval`.
\*\* Passing in an ID value other than the one returned by `setInterval` is undefined behavior and may cause problems. \*\*

## Example

## Notices

1. `setTimeout()` and `setInterval()` have a shared pool of ID numbers, so technically `clearTimeout()` and `clearInterval()` are interchangeable. However, for clarity, you should avoid doing so.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.clearInterval`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/clearInterval](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Cancels the timer set by `setInterval`.




---
url: /api/lynx-api/global/clear-timeout.md
---

# clearTimeout() global function

<APISummary />

Cancel the timer set by `setTimeout`.

## Syntax

```typescript
  clearTimeout(timerId: number): void;
```

### Parameter

#### timerId

The timer ID returned by `setTimeout`.
If the timer corresponding to this ID has already finished executing, the method will not perform any action.

\*\* Passing in an ID value that is not returned by `setTimeout` is undefined behavior and may cause problems. \*\*

## Example

## Notes

1. `setTimeout()` and `setInterval()` have a shared pool of ID numbers, so technically `clearTimeout()` and `clearInterval()` are interchangeable. However, for clarity, you should avoid doing so.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.clearTimeout`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/API/clearTimeout](https://developer.mozilla.org/zh-CN/docs/Web/API/clearTimeout)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Cancel the timer set by `setTimeout`.




---
url: /api/lynx-api/global/console/assert.md
---

# console: assert() method

<APISummary />

`assert` writes an error message to the console if the assertion is false. If the assertion is true, nothing happens.

## Syntax

```ts
assert(assertion: boolean, val1, val2, ...): undefined;
```

### Parameters

#### assertion

Any boolean expression. If the assertion is false, a generic message indicating assertion failure is written to the console.

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.assert`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** assert failed and output error level message




---
url: /api/lynx-api/global/console/count.md
---

# console: count() method

<APISummary />

`count` logs the number of times that this particular call to count() has been called.

## Syntax

```ts
count(label: string?): undefined;
```

### Parameters

#### label

A string. If supplied, count() outputs the number of times it has been called with that label. If omitted, count() behaves as though it was called with the "default" label.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.count`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** start count




---
url: /api/lynx-api/global/console/countReset.md
---

# console: countReset() method

<APISummary />

`countReset` resets counter used with console.count().

## Syntax

```ts
countReset(label: string?): undefined;
```

### Parameters

#### label

A string. If supplied, countReset() resets the count for that label to 0. If omitted, countReset() resets the default counter to 0.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.countReset`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** reset count




---
url: /api/lynx-api/global/console/debug.md
---

# console: debug() method

<APISummary />

`debug` outputs a message to the console at the "debug" log level.

## Syntax

```ts
debug(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.debug`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** output a debug level message




---
url: /api/lynx-api/global/console/error.md
---

# console: error() method

<APISummary />

`error` outputs a message to the console at the "error" log level.

## Syntax

```ts
error(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** output a error level message




---
url: /api/lynx-api/global/console/group.md
---

# console: group() method

<APISummary />

`group` creates a new inline group in the console log, causing any subsequent console messages to be indented by an additional level, until console.groupEnd() is called.

## Syntax

```ts
group(label: string?): undefined;
```

### Parameters

#### label

Label for the group.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.group`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** start a console group




---
url: /api/lynx-api/global/console/groupCollapsed.md
---

# console: groupCollapsed() method

<APISummary />

`groupCollapsed` creates a new inline group in the console. Unlike console.group(), however, the new group is created collapsed. The user will need to use the disclosure button next to it to expand it, revealing the entries created in the group.

## Syntax

```ts
groupCollapsed(label: string?): undefined;
```

### Parameters

#### label

Label for the group.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.groupCollapsed`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** start a collapsed console group




---
url: /api/lynx-api/global/console/groupEnd.md
---

# console: groupEnd() method

<APISummary />

`groupEnd` exits the current inline group in the console.

## Syntax

```ts
groupEnd(): undefined;
```

### Parameters

None.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.groupEnd`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** end a console group




---
url: /api/lynx-api/global/console/info.md
---

# console: info() method

<APISummary />

`info` 方法用于在控制台面板输出信息，日志级别为 info 级别。

## Syntax

```ts
info(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

输出的JavaScript值列表。这些值中的每个值的表示形式都以给定的顺序输出。

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.info`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** output a info level message




---
url: /api/lynx-api/global/console/log.md
---

# console: log() method

<APISummary />

`log` outputs a message to the console.

## Syntax

```ts
log(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.log`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** output a log level message




---
url: /api/lynx-api/global/console/profile.md
---

# console: profile() method

<APISummary />

`profile` starts recording a performance profile.

## Syntax

```ts
profile(profileName: string): undefined;
```

### Parameters

#### profileName

The name to give the profile.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.profile`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** output a message




---
url: /api/lynx-api/global/console/profileEnd.md
---

# console: profileEnd() method

<APISummary />

`profileEnd` stops recording a profile previously started with console.profile().

## Syntax

```ts
profileEnd(profileEndName: string): undefined;
```

### Parameters

#### profileEndName

The name to give the profile.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.profileEnd`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** end profile




---
url: /api/lynx-api/global/console/table.md
---

# console: table() method

<APISummary />

`table` displays tabular data as a table.

## Syntax

```ts
table(data: any, columns: array?): undefined;
```

### Parameters

#### data

The data to display. This must be either an array or an object. Each item in the array, or property in the object, is represented by a row in the table. The first column in the table is labeled (index) and its values are the array indices or the property names.

#### columns

An array which can be used to restrict the columns shown in the table. It contains indices, if each entry of data is an array, or property names, if each entry of data is an object. The resulting table then includes only columns for items which match the given indices or names.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.table`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** print message by table




---
url: /api/lynx-api/global/console/time.md
---

# console: time() method

<APISummary />

`time` starts a timer you can use to track how long an operation takes.

## Syntax

```ts
time(label: string?): undefined;
```

### Parameters

#### label

A string representing the name to give the new timer.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.time`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** start a timer




---
url: /api/lynx-api/global/console/timeEnd.md
---

# console: timeEnd() method

<APISummary />

`timeEnd` stops a timer that was previously started by calling console.time().

## Syntax

```ts
timeEnd(label: string?): undefined;
```

### Parameters

#### label

A string representing the name to give the new timer.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.timeEnd`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** end a timer




---
url: /api/lynx-api/global/console/timeLog.md
---

# console: timeLog() method

<APISummary />

`timeLog` logs the current value of a timer that was previously started by calling console.time().

## Syntax

```ts
timeLog(label: string?): undefined;
```

### Parameters

#### label

The name of the timer to log to the console. If this is omitted the label "default" is used.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.timeLog`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** print timer




---
url: /api/lynx-api/global/console/warn.md
---

# console: warn() method

<APISummary />

`warn` outputs a warning message to the console at the "warning" log level.

## Syntax

```ts
warn(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.warn`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** output a warn level message




---
url: /api/lynx-api/global/fetch.md
---

<APISummary />

## Syntax

```typescript
fetch(resource);
fetch(resource, options);
```

### Parameters

#### resource

This defines the resource that you wish to fetch. This can either be:

- A string or any other object with stringify API — including a URL object — that provides the URL of the resource you want to fetch.

- A `Request` object.

#### options

A `RequestInit` object containing any custom settings that you want to apply to the request.

## Example

```typescript
const request = new Request('https://jsonplaceholder.typicode.com/todos/1');
const response = await fetch(request);
console.log(await response.json());
```

## Compatibility

:::info

- Client environment are different from Web, Lynx does not support Web-only features like: [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)、redirect、keepalive related APIs. FormData/Blob related APIs are not supported.

- Web Platform supports Fetch API using Browser's Fetch implementation, it follows the same rules as the web.

:::

**Compatibility Table**
**Query:** `lynx-api.fetch.fetch`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>fetch</code>


### Headers

**Compatibility Table**
**Query:** `lynx-api.fetch.Headers`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Headers](https://developer.mozilla.org/docs/Web/API/Headers)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Web | ✅ Yes | - |


### Request

**Compatibility Table**
**Query:** `lynx-api.fetch.Request`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Request](https://developer.mozilla.org/docs/Web/API/Request)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Web | ✅ Yes | - |


### Response

**Compatibility Table**
**Query:** `lynx-api.fetch.Response`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Response](https://developer.mozilla.org/docs/Web/API/Response)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/global/set-interval.md
---

# setInterval() global function

<APISummary />

Repeatedly calls a function or executes a code fragment with a fixed time interval between each call.

## Syntax

```typescript
setInterval(function: () => void, delay: number): number;
```

### Parameters

#### function

Functions to be called repeatedly are executed after every specified `delay` milliseconds. The first call occurs after `delay` milliseconds.

#### delay

The time interval between repeated function calls, in milliseconds.

The js thread may be frozen while the app is in the background. Therefore, the actual delay of `setInterval` may be greater than the specified value. At the same time, the duration of the js thread being frozen will still be counted in the delay of `setInterval`. In this case, the specified function will only be called once immediately after the app wakes up, even if the js thread is frozen for a number of times longer than `delay`.

### Return value

Returns a positive integer representing the ID value of the timer. This ID value can be used to cancel the timer.

The front-end code should not make any assumptions about the actual value of the returned ID.

## Example

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.setInterval`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Repeatedly calls a function or executes a code fragment with a fixed time interval between each call.




---
url: /api/lynx-api/global/set-timeout.md
---

# setTimeout() global function

<APISummary />

The `setTimeout` method sets a timer that executes the specified function when it expires.

## Syntax

```typescript
setTimeout(function: () => void, delay?: number): number;
```

### Parameters

#### function

The function to be executed after the expiration time.

#### delay (Optional)

The number of milliseconds of delay after which the function call will occur.
If this parameter is omitted, `delay` takes the default value of 0, specifying that the function will be executed after the execution of existing tasks queued in the js thread task queue.

The js thread may be frozen while the app is in the background. As a result, the actual delay of `setTimeout` may be longer than the specified value.
Also, the duration of the frozen js thread will still be counted in the delay of `setTimeout`.

### Return Value

Returns a positive integer representing the ID value of the timer.
This ID value can be used to cancel the timer.

The front-end code should not make any assumptions about the actual value of the returned ID.

## Example

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.setTimeout`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/global/system-info.md
---

<APISummary />

# SystemInfo

`SystemInfo` is a plain JavaScript object that contains information of the current system.

## Syntax

```ts
declare const SystemInfo: {
  /**
   * The version of the Lynx Engine.
   *
   * @example '3.2'
   */
  readonly engineVersion: string;

  /**
   * The version of the Lynx Engine.
   * @example '3.2'
   * @deprecated Use `SystemInfo.engineVersion` instead
   */
  readonly lynxSdkVersion: string;

  /**
   * The current operating system version.
   */
  readonly osVersion: string;

  /**
   * The physical pixel height of the real device.
   */
  readonly pixelHeight: number;

  /**
   * The physical pixel width of the real device.
   */
  readonly pixelWidth: number;

  /**
   * The physical pixel ratio of the main screen.
   */
  readonly pixelRatio: number;

  /**
   * The platform of the current device.
   */
  readonly platform: 'Android' | 'iOS' | 'macOS' | 'windows' | 'headless';

  /**
   * The JavaScript engine currently used.
   * @note Not avaliable in lepus
   */
  readonly runtimeType: 'v8' | 'jsc' | 'quickjs';
};
```

### Fields

#### engineVersion

The Lynx Engine version, in format `major.minor`.

E.g.: `3.2`.

#### ~~lynxSdkVersion~~

The Lynx Engine version, in format `major.minor`.

E.g.: `3.2`.

#### osVersion

A string representing the current version of the operating system.

<Tabs groupId="os">
  <Tab value="ios" label="iOS">
    > [systemVersion | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uidevice/1620043-systemversion?language=objc)

    ```objc
    [[UIDevice currentDevice].systemVersion UTF8String]
    ```
  </Tab>

  <Tab value="android" label="Android">
    Equivalent to the Java [`Build.VERSION.SDK_INT`](https://developer.android.com/reference/android/os/Build.VERSION#SDK_INT) API.

    > [API Levels | Android NDK | Android Developers](https://developer.android.com/ndk/reference/group/apilevels#android_get_device_api_level)

    ```cpp
    std::to_string(android_get_device_api_level())
    ```
  </Tab>
</Tabs>

#### pixelHeight

The absolute height of the available display size in pixels.

<Tabs groupId="os">
  <Tab value="ios" label="iOS">
    > [UIScreen | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uiscreen?language=objc)

    ```objc
    CGSize screenSize;
    if (!CGSizeEqualToSize(builder.screenSize, CGSizeZero)) {
      screenSize = builder.screenSize;
    } else {
      screenSize = [UIScreen mainScreen].bounds.size;
    }
    const CGFloat scale = [UIScreen mainScreen].scale;
    // highlight-next-line
    const CGFloat pixelHeight = screenSize.height * scale;
    ```
  </Tab>

  <Tab value="android" label="Android">
    > [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics)

    ```java
    DisplayMetrics dm = context.getResources().getDisplayMetrics();
    // highlight-next-line
    int pixelHeight = dm.heightPixels;
    ```
  </Tab>
</Tabs>

#### pixelWidth

The absolute width of the available display size in pixels.

<Tabs groupId="os">
  <Tab value="ios" label="iOS">
    > [UIScreen | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uiscreen?language=objc)

    ```objc
    CGSize screenSize;
    if (!CGSizeEqualToSize(builder.screenSize, CGSizeZero)) {
      screenSize = builder.screenSize;
    } else {
      screenSize = [UIScreen mainScreen].bounds.size;
    }
    const CGFloat scale = [UIScreen mainScreen].scale;
    // highlight-next-line
    const CGFloat pixelWidth = screenSize.width * scale;
    ```
  </Tab>

  <Tab value="android" label="Android">
    > [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics)

    ```java
    DisplayMetrics dm = context.getResources().getDisplayMetrics();
    // highlight-next-line
    int pixelWidth = dm.widthPixels;
    ```
  </Tab>
</Tabs>

#### pixelRatio

The natural scale factor associated with the screen.

<Tabs groupId="os">
  <Tab value="ios" label="iOS">
    > [UIScreen | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uiscreen?language=objc)

    ```objc
    const CGFloat pixelRatio = [UIScreen mainScreen].scale;
    ```
  </Tab>

  <Tab value="android" label="Android">
    > [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics#density)

    ```java
    DisplayMetrics dm = context.getResources().getDisplayMetrics();
    // highlight-next-line
    float pixelRatio = dm.density;
    ```
  </Tab>
</Tabs>

#### platform

The platform of the current device.

Candidate values:

1. `iOS`
2. `Android`
3. `macOS`
4. `windows`

#### runtimeType

The JavaScript engine currently used.

:::info
This is only avaliable in the background thread.
:::

Candidate values:

1. `quickjs`
2. `jsc`
3. `v8`

See [JavaScript Environment](/guide/scripting-runtime/index.md) for more details.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.SystemInfo`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | 1.0 | only support SystemInfo.platform; ⚠️ Partial implementation |

**Description:** Information of the current system




---
url: /api/lynx-api/intersection-observer.md
---

# IntersectionObserver

<APISummary />

`IntersectionObserver` is used to observe the intersection status between the target node and the reference node and the target node and the ancestor node. When the intersection status changes, the corresponding callback is triggered. Based on this, you can monitor whether the target node is exposed/de-exposed.

## Instance method

[`IntersectionObserver.relativeTo()`](/api/lynx-api/intersection-observer/intersection-observer-relative-to.md)

Specify the reference node, which is specified based on `id`.

[`IntersectionObserver.relativeToViewport()`](/api/lynx-api/intersection-observer/intersection-observer-relative-to-viewport.md)

Specify `LynxView` as the reference node.

[`IntersectionObserver.relativeToScreen()`](/api/lynx-api/intersection-observer/intersection-observer-relative-to-screen.md)

Specify the screen as the reference node.

[`IntersectionObserver.observer()`](/api/lynx-api/intersection-observer/intersection-observer-observe.md)

Specify the target node and callback. The target node is specified based on `id`.

[`IntersectionObserver.disconnect()`](/api/lynx-api/intersection-observer/intersection-observer-disconnect.md)

Clear the target node and callback, the target node will no longer be observed, and the corresponding callback will not be triggered.

## Example

You can observe changes in the intersection status of the target node and the reference node through the following three steps:

1. Create an `IntersectionObserver` object and specify a threshold list for intersection state changes
2. Call the `relativeTo*` method of the `IntersectionObserver` object to specify the reference node
3. Call the `observe` method of the `IntersectionObserver` object to specify the target node and callback
4. Call the `disconnect` method of the `IntersectionObserver` object to clear the target node and callback

```tsx
// 1. Create IntersectionObserver object
const observer = lynx.createIntersectionObserver(this, {
  thresholds: [0, 0.25, 0.5, 0.75, 1.0],
});

// 2. Call the relativeTo method to specify the reference node
observer.relativeTo('#refNode', { left: 10, right: 10 });

// 3. Call the observe method to specify the target node and callback
observer.observe('#targetNode', (res) => {
  console.log('IntersectionObserver: ', JSON.stringify(res));
});

// 4. Call the disconnect method to clear the target node and callback
observer.disconnect();
```

## Precautions

- It is recommended to set the page switch `enableNewIntersectionObserver` to `true`, otherwise the scrollable container needs to be bound to the corresponding scroll event (such as `scroll`) to trigger the corresponding callback.
- When using `relativeTo` and `observe` methods, you need to pay attention to the calling timing and ensure that the reference node and target node have been created when calling. Otherwise, the observation will be invalid, that is, the corresponding callback will never be triggered.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.IntersectionObserver`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Observe the intersection status between the target node and the reference node and the target node and the ancestor node. When the intersection status changes, the corresponding callback is triggered. Based on this, you can monitor whether the target node is exposed/de-exposed.




---
url: /api/lynx-api/intersection-observer/intersection-observer-disconnect.md
---

# IntersectionObserver: disconnect() method

<APISummary />

The `disconnect` method can be used to clear the target node and callback. The target node will no longer be observed and the corresponding callback will not be triggered. If you need to re-observe the target node, you need to re-specify the target node and callback.

## grammar

```ts
disconnect(): void;
```

### Parameters

None (`undefined`).

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.disconnect`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Clear the target node and callback. The target node will no longer be observed and the corresponding callback will not be triggered.




---
url: /api/lynx-api/intersection-observer/intersection-observer-observe.md
---

# IntersectionObserver: observe() method

<APISummary />

`observe` specifies the target node and callback, and the target node is specified according to `id`.

## grammar

```ts
observe(selector: string, callback: Function): void;
```

### Parameters

#### selector

```ts
selector: string;
```

Specify the id used when searching for the target node. The `id` will be searched first in the `component` passed in when creating the `IntersectionObserver` object. If not found, the global search will be performed. If the global search is not found, the specification will be invalid.

#### callback

```ts
callback: (res) => {};
```

Specify the callback triggered when the intersection status of the target node and the reference node changes.
The format of the callback parameter `res` is as follows:

```ts
{
     "isIntersecting": boolean, // Whether the target node intersects with the reference node
     "intersectionRatio": number, // The intersection ratio between the target node and the reference node
     "intersectionRect": object, // The intersection area between the target node and the reference node
     "boundingClientRect": object, // The intersection area of the target node
     "relativeRect": object, // The intersection area of the reference node
     "observerId": string, // The id of the target node
     "time": number, // timestamp during intersection detection (not implemented, now returns are all 0)
}
```

The structures of `intersectionRect`, `boundingClientRect` and `relativeRect` are the same. The coordinate systems are all relative to `LynxView`, that is, the upper left corner of `LynxView` is the origin of the coordinate system, with the horizontal direction to the right being the positive direction of the `x`-axis, and the vertical direction being downwards being the positive direction of the `y`-axis:

```ts
{
     "left": number | 0, // left boundary of the intersection area
     "right": number | 0, // Right boundary of the intersection area
     "top": number | 0, // The upper boundary of the intersection area
     "bottom": number | 0, // The lower boundary of the intersection area
}
```

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.observe`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Specify the target node and callback, and the target node is specified according to id.




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to-screen.md
---

# IntersectionObserver: relativeToScreen() method

<APISummary />

The `relativeToScreen` method can be used to specify the screen as the reference node, and the reference node's viewport can be scaled according to `margins`.

## grammar

```ts
relativeToScreen(
   margins ? margins : {left: 0, right: 0, top: 0, bottom: 0}
): IntersectionObserver;
```

### Parameters

#### margins

```ts
margins ? margins : { left: 0, right: 0, top: 0, bottom: 0 };
```

Specifies the zoom value of the reference node window. This value only affects the detection of the intersection state and does not affect the actual view display. A positive value means expanding the reference node window boundary, and a negative value means shrinking the reference node window boundary.

| Property name | Type              | Description                                                |
| ------------- | ----------------- | ---------------------------------------------------------- |
| `left`        | `number ｜ string` | The scaling value of the left boundary of the target node  |
| `right`       | `number ｜ string` | The scaling value of the right boundary of the target node |
| `top`         | `number ｜ string` | The scaling value of the upper boundary of the target node |
| `bottom`      | `number ｜ string` | The scaling value of the lower boundary of the target node |

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

### Precautions

The intersection state between the target node and the reference node and the target node and the ancestor node is defined as the smallest intersection ratio as follows:

- The intersection ratio of the target node and the screen (scaled by `margins`)
- The intersection ratio between the target node and `LynxView`
- The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to `LynxView`. The ancestor node will be ignored when `overflow: visible` is set.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.relativeToScreen`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.10 | - |
| iOS | 2.10 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Specify the screen as the reference node.




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to-viewport.md
---

# IntersectionObserver: relativeToViewport() method

<APISummary />

The `relativeToViewport` method can be used to specify a `LynxView` as a reference node, and the reference node's viewport can be scaled according to `margins`.

## grammar

```ts
relativeToViewport(
   margins ? margins : {left: 0, right: 0, top: 0, bottom: 0}
): IntersectionObserver;
```

### Parameters

#### margins

```ts
margins ? margins : { left: 0, right: 0, top: 0, bottom: 0 };
```

Specifies the zoom value of the reference node window. This value only affects the detection of the intersection state and does not affect the actual view display. A positive value means expanding the reference node window boundary, and a negative value means shrinking the reference node window boundary.

| Property name | Type              | Description                                                |
| ------------- | ----------------- | ---------------------------------------------------------- |
| `left`        | `number ｜ string` | The scaling value of the left boundary of the target node  |
| `right`       | `number ｜ string` | The scaling value of the right boundary of the target node |
| `top`         | `number ｜ string` | The scaling value of the upper boundary of the target node |
| `bottom`      | `number ｜ string` | The scaling value of the lower boundary of the target node |

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

### Precautions

The intersection state between the target node and the reference node and the target node and the ancestor node is defined as the smallest intersection ratio as follows:

- The intersection ratio between the target node and `LynxView` (scaled by `margins`)
- The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to `LynxView`. The ancestor node will be ignored when `overflow: visible` is set.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.relativeToViewport`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Specify a LynxView as a reference node.




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to.md
---

# IntersectionObserver: relativeTo() method

<APISummary />

The `relativeTo` method can be used to specify a reference node. The reference node is specified by `id`. The viewport of the reference node can be scaled according to `margins`.

## grammar

```ts
relativeTo(
   selector: string,
   margins ? margins : {left: 0, right: 0, top: 0, bottom: 0}
): IntersectionObserver;
```

### Parameters

#### selector

```ts
selector: string;
```

Specify the `id` used when searching for the reference node. It will first search in the `component` passed in when creating the `IntersectionObserver` object. If not found, the global search will be performed. If the global search is not found, `LynxView` will be used as the reference node.

#### margins

```ts
margins ? margins : { left: 0, right: 0, top: 0, bottom: 0 };
```

Specifies the zoom value of the reference node window. This value only affects the detection of the intersection state and does not affect the actual view display. A positive value means expanding the reference node window boundary, and a negative value means shrinking the reference node window boundary.

| Property name | Type              | Description                                                |
| ------------- | ----------------- | ---------------------------------------------------------- |
| `left`        | `number ｜ string` | The scaling value of the left boundary of the target node  |
| `right`       | `number ｜ string` | The scaling value of the right boundary of the target node |
| `top`         | `number ｜ string` | The scaling value of the upper boundary of the target node |
| `bottom`      | `number ｜ string` | The scaling value of the lower boundary of the target node |

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

### Precautions

The intersection state between the target node and the reference node and the target node and the ancestor node is defined as the smallest intersection ratio as follows:

1. When the reference node is valid, that is, the reference node is the ancestor node of the target node, select the smallest
   - The intersection ratio of the target node and the reference node (scaled by `margins`)
   - The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to the reference node. The ancestor node will be ignored when `overflow: visible` is set.
2. When the reference node is invalid, that is, the reference node is not the ancestor node of the target node or there is no node with the `id` set, select the smallest one below
   - The intersection ratio between the target node and `LynxView` (scaled by `margins`)
   - The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to `LynxView`. The ancestor node will be ignored when `overflow: visible` is set.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.relativeTo`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Specify a reference node. The reference node is specified by id.




---
url: /api/lynx-api/lynx.md
---




---
url: /api/lynx-api/lynx/lynx-accessibility-announce.md
---

# lynx: accessibilityAnnounce() static method

<APISummary />

Makes screen readers announce the specified text content, helping visually impaired users perceive interface state changes or operation results.

## Syntax

```ts
accessibilityAnnounce({"content" : string}) : void;
```

### Parameter

#### `content`

The text content to be announced

## 示例

```jsx
lynx.accessibilityAnnounce(
  {
    content: 'hello lynx',
  },
  (res) => {
    console.log('test: ' + JSON.stringify(res));
  },
);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.accessibilityAnnounce`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to have the specified text content read by the screen reader.




---
url: /api/lynx-api/lynx/lynx-add-font.md
---

# lynx: addFont() static method

<APISummary />

Used for dynamically adding fonts.

## Syntax

```ts
export interface FontFace {
  'font-family': string;
  'src': string;
}

addFont(fontFace: FontFace, callback?: () => void): void;
```

### Parameter

#### fontFace

The font to be added.

#### callback

The callback after adding the font.

## Example

```ts
lynx.addFont(
  {
    'font-family': 'CustomFont',
    src: 'url("xxx")',
  },
  () => {
    console.log('load font');
  },
);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.addFont`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.12 | - |
| iOS | 2.12 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Used for dynamically adding fonts.




---
url: /api/lynx-api/lynx/lynx-animate-api.md
---

# animate()

<APISummary />

## Introduction

Use `animate()` to set a [CSS Animation](/api/css/properties/animation.md) on UI elements.

1. Use the [getElementById](/api/lynx-api/lynx/lynx-get-element-by-id.md) API to find the `Element` object that needs to be animated based on its `id`.
2. Call the `animate` API on the `Element` object to achieve animation.

## Syntax

```js
animate(keyframes, options);
```

### Parameter

#### keyframes

There are **two different formats**:

1. An **array** consisting of objects that contain properties and values of multiple keyframes.

```js
element.animate(
  [
    {
      // from
      opacity: 0,
      color: '#fff',
    },
    {
      // to
      opacity: 1,
      color: '#000',
    },
  ],
  2000,
);
```

2. An **object** consisting of keys as offsets and values as keyframes.

```js
element.animate({
  '0%': {
    // from
    opacity: 0,
    color: '#fff',
  },
  '50%': {
    // 50%
    opacity: 0.5,
    color: '#aaa',
  },
  '100%': {
    // to
    opacity: 1,
    color: '#000',
  },
});
```

3. You can also assign a [timing-function](/api/css/properties/animation-timing-function.md) for each keyframe.

```js
element.animate([
  {
    // from
    opacity: 0,
    color: '#fff',
    'animation-timing-function': 'linear',
  },
  {
    // to
    opacity: 1,
    color: '#000',
    'animation-timing-function': 'ease-in',
  },
]);
```

#### options

An **object** that contains one or more properties:

| Key        | Value Type | Optional | Description                                                                                                                                                                                                                                                                        | Default Value          |
| ---------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| duration   | Number     | optional | The length of time for the animation to run.                                                                                                                                                                                                                                       | 0                      |
| delay      | Number     | optional | The length of time to wait before starting the animation.                                                                                                                                                                                                                          | 0                      |
| iterations | Number     | optional | The number of times the animation should repeat. You can set this to `Infinity` to make the animation loop indefinitely.                                                                                                                                                           | 1                      |
| direction  | String     | optional | Whether the animation runs forwards (`normal`), backwards (`reverse`), switches direction after each iteration (`alternate`), or runs backwards and switches direction after each iteration (`alternate-reverse`). Defaults to `"normal"`.                                         | `"normal"`             |
| easing     | String     | optional | The rate of the animation's change over time. Accepts an [timing-function](/api/css/properties/animation-timing-function.md), such as `"linear"`, `"ease-in"`, or `"cubic-bezier(0.42, 0, 0.58, 1)"`. Defaults to "linear".                                                        | `"linear"`             |
| fill       | String     | optional | Dictates whether the animation's effects should be reflected by the element(s) prior to playing ("backwards"), retained after the animation has completed playing ("forwards"), or both. Defaults to "none".                                                                       | `"none"`               |
| name       | String     | optional | The name of the animation, which can be used to uniquely identify it. This name appears in the [animation events](/api/lynx-api/event/animation-event.md#animation) parameters and is typically used to determine if a particular animation event is the one you're interested in. | An internal unique ID. |
| play-state | String     | optional | Animation motion state, which defines whether an animation is running or paused, accepts an [animation-play-state](/api/css/properties/animation-play-state.md)                                                                                                                    | running                |

:::info Note:

1. If no `name` is specified, a unique id is generated incrementally.
2. An animation with the same `name` cannot be triggered consecutively multiple times.

:::

### Return Value

Returns an `Animation` object.
The `Animation` object has the following methods:

| Method Name          | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `Animation.cancel()` | Cancels the animation and triggers the `animation cancel` event. |
| `Animation.pause()`  | Pauses the animation.                                            |
| `Animation.play()`   | Resumes the animation.                                           |

## Example

### by getElementById()

```js
let ani = lynx.getElementById('test').animate(
  [
    {
      'background-color': 'blue',
      transform: 'translateX(100px) translateY(300px) rotate(360deg)',
    },
    {
      'background-color': 'red',
      transform: 'translateX(0px) translateY(600px) rotate(0deg)',
    },
  ],
  {
    duration: 3000,
    delay: 1000,
    iterations: Infinity,
    direction: 'alternate',
    easing: 'ease-in-out',
    fill: 'both',
  },
);

// When the parameter is Object, it is strictly required to write percentages with a percent sign such as '.50' and '50' equivalents are divided by 100
let ani = lynx.getElementById('test').animate(
  {
    '0%': {
      transform: 'rotate(0deg)',
      left: '0px',
    },
    '50%': {
      // The properties of the intermediate frame can default.
      left: '30px',
    },
    '100%': {
      transform: 'rotate(225deg)',
      left: '100px',
    },
  },
  {
    duration: 3000,
    delay: 1000,
    iterations: Infinity,
    direction: 'alternate',
    easing: 'ease-in-out',
    fill: 'both',
  },
);

ani.pause();
ani.play();
ani.cancel();
```

::: note

- Each call to `getElementById("test").animate` will generate a new `Animation` object, and the later created animation will override the previous ones.
- If you want to restart the same animation, you need to call `getElementById("test").animate` again to create a new `Animation` object.

:::

### by createSelectorQuery() <VersionBadge>3.4</VersionBadge>

After **Lynx version 3.4**, the `animate()` can be called via the `createSelectorQuery()`.

**It's an experimental feature, and you should use it with caution.**

```js
const ani1 = lynx.createAnimation(
  'ani1',
  [
    {
      transform: 'translateY(0px)',
    },
    {
      transform: 'translateY(-150px)',
    },
  ],
  {
    name: 'js-animation-1',
    duration: 3000,
    iterations: 'infinite',
    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
    fill: 'forwards',
  },
);

// start
this.createSelectorQuery().select('#test').animate([ani1]).exec();
// pause
this.createSelectorQuery()
  .select('#test')
  .pauseAnimation(['js-animation-1'])
  .exec();
```

### Multiple animate <VersionBadge>3.4</VersionBadge>

After **Lynx version 3.4**, you can chain multiple animation with `createSelectorQuery()`.

**It's an experimental feature, and you should use it with caution.**

```js
const ani1 = lynx.createAnimation(
  'ani1',
  [
    {
      transform: 'translateY(0px)',
    },
    {
      transform: 'translateY(-150px)',
    },
  ],
  {
    name: 'js-animation-1',
    duration: 3000,
    iterations: 'infinite',
    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
    fill: 'forwards',
  },
);

const ani2 = lynx.createAnimation(
  'ani2',
  [
    {
      'background-color': 'red',
    },
    {
      'background-color': 'blue',
    },
  ],
  {
    name: 'js-animation-2',
    duration: 3000,
    easing: 'linear',
    fill: 'forwards',
    iterations: 'infinite',
  },
);

// start
this.createSelectorQuery().select('#test').animate([ani1, ani2]).exec();
// pause
this.createSelectorQuery()
  .select('#test')
  .pauseAnimation(['js-animation-1', 'js-animation-2'])
  .exec();
```

## Animation Event

The events for the `animate()` API are the same as the [animation events](/api/lynx-api/event/animation-event.md#animation) for CSS animations.

## Other Infos

:::tip

- Animate Api and CSS Animation will override each other, and the one that takes effect later will override the former.

- The Animate API may not take effect, possibly because `getElementById` failed to select the node:
  - The ID selector might be incorrect
  - The value of the ID selector might depend on a complex JS expression, causing the value of the ID selector not to be available on the first screen. In this case, if getElementById is invoked too early (like in ComponentDidMount), it might not find the node.

:::

## See also

- [Introduction to CSS Animations](/guide/styling/animation.md)
- [Animate API in MTS](/api/lynx-api/main-thread/lynx-animate-api.md)

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.animateAPI`


---
url: /api/lynx-api/lynx/lynx-before-publish-event.md
---

# BeforePublishEvent

<APISummary />

`lynx.beforePublishEvent` is used to register/remove listening for an element event.

## Instance methods

[`BeforePublishEvent.add()`](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md)

Register a listener for an element event.

[`BeforePublishEvent.remove()`](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md)

Remove listening for an element event.

## Example

Register/remove listening for a certain element event.

```tsx
//Register to listen for the tap event
lynx.beforePublishEvent.add('tap', this.handleTap);

//Remove monitoring of tap event
lynx.beforePublishEvent.remove('tap', this.handleTap);
```

## Precautions

Since this is an aspect interface on the background thread, the element element needs to be bound to the corresponding event and triggered, so that the aspect interface can listen to the element event.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.lynx-before-publish-event.BeforePublishEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Used to register/remove monitoring of an element event




---
url: /api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md
---

# BeforePublishEvent: add() method

<APISummary />

The `add` method can be used to register listening for a certain element event.

## grammar

```ts
add(name: string, listener: () => {}, context?: BaseInstance): BeforePublishEvent;
```

### Parameters

#### name

```ts
name: string;
```

Specify the name of the element event to be listened to.

#### listener

```ts
listener: () => {};
```

Specify the listening callback.

#### context

```ts
context?: BaseInstance
```

Front-end custom `component` or `card` instance.

### return value

`BeforePublishEvent` object.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.lynx-before-publish-event.add`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Register to listen for an element event.




---
url: /api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md
---

# BeforePublishEvent: remove() method

<APISummary />

The `remove` method can be used to remove listening for a certain element event.

## grammar

```ts
remove(name: string, listener: () => {}): BeforePublishEvent;
```

### Parameters

#### name

```ts
name: string;
```

Specifies the name of the element event to be listened to.

#### listener

```ts
listener: () => {};
```

Specify the listening callback.

### return value

`BeforePublishEvent` object.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.lynx-before-publish-event.remove`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Remove monitoring of an element event.




---
url: /api/lynx-api/lynx/lynx-cancel-animation-frame.md
---

# lynx: cancelAnimationFrame() static method

<APISummary />

Cancel a [`requestAnimationFrame`] callback.

## Syntax

```ts
cancelAnimationFrame: (requestID: number) => void;
```

### Parameters

#### requestID

The return value of the [`requestAnimationFrame`] that needs to be cancelled.

### Return Value

None (`undefined`).

[`requestAnimationFrame`]: /api/lynx-api/lynx/lynx-request-animation-frame.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.cancelAnimationFrame`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Cancel a `requestAnimationFrame` callback.




---
url: /api/lynx-api/lynx/lynx-cancel-resource-prefetch.md
---

# lynx: cancelResourcePrefetch() static method

<APISummary />

- This API is used to cancel resource preloading initiated by [requestResourcePrefetch](/api/lynx-api/lynx/lynx-request-resource-prefetch.md).

## Syntax

```ts
cancelResourcePrefetch(data: object, callback: (res: object) => void) : void;
```

### Parameters

#### `data`

A collection that describes the details of all resources to be canceled for preloading, with its keys defined as follows:

- `data`: Type `array`, each item inside the array corresponds to a resource. The keys for each item are defined as follows:
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of resource. The supported resource types are defined as follows:
    - `video`: Audio/video resources (preloading cancellation for image resources is currently not supported)
  - `params`: Custom control parameters for canceling preloading, the supported parameters are as follows:
    - `preloadKey`: Only for `video` type resources. Represents a unique key that identifies the resource. It is necessary to ensure that the `preloadKey` passed here is consistent with that used when calling [requestResourcePrefetch](/api/lynx-api/lynx/lynx-request-resource-prefetch.md). This is a required parameter.

#### `callback`

The callback function that is called after the API execution is completed or fails. The structure of its return parameters is as follows:

- `code`: Type `number`, status code, which may take the following values:
  - `0`: Success
  - `11001`: Parameter error
- `msg`: Type `string`, a global error message
- `details`: Type `array`, where each detail represents the cancelation status details of a resource. The structure of each detail is as follows:
  - `code`: Type `number`, status code, which may take the following values:
    - `0`: Success
    - `11001`: Parameter error
  - `msg`: Type `string`, error message
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of the resource, defined as follows:
    - `video`: Audio/video resources

### Return Value

None (`undefined`).

## Exceptions

- When there is a parameter error, `code` will return the `11001` error code, and the `msg` will contain detailed error information.

## Example

```js
import { useEffect } from '@lynx-js/react';

function Page() {
  // We need to preload two videos.
  // First, prepare the resource parameters, assigning the necessary preloadKey to the videos.
  let resData = [
    {
      uri: 'https://zzzzz1.mp4',
      type: 'video',
      params: { preloadKey: 'zzzzz1' },
    },
    {
      uri: 'https://zzzzz2.mp4',
      type: 'video',
      params: { preloadKey: 'zzzzz2' },
    },
  ];

  useEffect(() => {
    // Call requestResourcePrefetch to initiate preloading
    lynx.requestResourcePrefetch?.(
      {
        data: resData,
      },
      (res) => {
        if (res.code == 0) {
          console.log('success!');
        } else {
          console.log('fail! ', res.msg);
        }
        console.log(
          'prefetch status of each resource:',
          JSON.stringify(res.details),
        );
      },
    );
  }, []);

  const handleTap = () => {
    // Trigger the cancellation of resource preloading on click
    // Call cancelResourcePrefetch to cancel the preloading
    lynx.cancelResourcePrefetch?.(
      {
        data: resData,
      },
      (res) => {
        if (res.code == 0) {
          console.log('success!');
        } else {
          console.log('fail! ', res.msg);
        }
        console.log(
          'cancel status of each resource:',
          JSON.stringify(res.details),
        );
      },
    );
  };

  return <view onTap={handleTap}>{/* ... */}</view>;
}

export default Page;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.cancelResourcePrefetch`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to cancel the prefetch of resource.




---
url: /api/lynx-api/lynx/lynx-create-intersection-observer.md
---

# lynx: createIntersectionObserver() static method

<APISummary />

The `lynx.createIntersectionObserver` method can be used to create an `IntersectionObserver` object. The object behavior can be customized by passing in parameters. Once the object is created, it cannot be modified.

## grammar

```ts
lynx.createIntersectionObserver(
   component: BaseInstance,
   options ? options : {
     thresholds : [0],
     initialRatio: 0,
     observeAll : false,
   }
): IntersectionObserver;
```

### Parameters

#### component

```ts
component: BaseInstance;
```

For front-end custom `component` or `card` instances, the target node and reference node are searched first in this `component`. If not found, the global search is performed.

#### options

```ts
options
  ? options
  : {
      thresholds: [0],
      initialRatio: 0,
      observeAll: false,
    };
```

Specify the behavior of `IntersectionObserver` objects:

- `thresholds`: The valid range of each array element is `[0, 1]`, specifying a threshold list for intersection state changes. When the intersection ratio of the target node and the reference node passes one of the thresholds, a callback is triggered, and the old intersection ratio is represented. and the new intersection ratio is on either side of the threshold or the intersection ratio is equal to the threshold
- `initialRatio`: The valid range is `[0, 1]`, which specifies the threshold for triggering the callback when detected for the first time. The callback is triggered when the intersection ratio of the first detection is greater than the threshold.
- `observeAll`: Specify whether to observe multiple target nodes at the same time

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

## Example

You can observe changes in the intersection status of the target node and the reference node through the following three steps:

1. Create an `IntersectionObserver` object and specify a threshold list for intersection state changes
2. Call the `relativeTo*` method of the `IntersectionObserver` object to specify the reference node
3. Call the `observe` method of the `IntersectionObserver` object to specify the target node and callback
4. Call the `disconnect` method of the `IntersectionObserver` object to clear the target node and callback

```tsx
// 1. Create IntersectionObserver object
const observer = lynx.createIntersectionObserver(this, {
  thresholds: [0, 0.25, 0.5, 0.75, 1.0],
});

// 2. Call the relativeTo method to specify the reference node
observer.relativeTo('#refNode', { left: 10, right: 10 });

// 3. Call the observer method to specify the target node and callback
observer.observe('#targetNode', (res) => {
  console.log('IntersectionObserver: ', JSON.stringify(res));
});

// 4. Call the disconnect method to clear the target node and callback
observer.disconnect();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.createIntersectionObserver`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Clay macOS | 3.5 | - |
| Web | ❌ No | - |

**Description:** Create an IntersectionObserver object.




---
url: /api/lynx-api/lynx/lynx-create-selector-query.md
---

# lynx: createSelectorQuery() static method

<APISummary />

Create a [`SelectorQuery`] with the root node of the page as the root.

## Syntax

```ts
createSelectorQuery(): SelectorQuery;
```

### Parameter

None.

### Return Value

A [`SelectorQuery`] object with the root node of the page as the root.

## Examples

Obtain the position and size of the specified `text` node:

```jsx
import { useEffect } from '@lynx-js/react';

function App() {
  useEffect(() => {
    lynx
      .createSelectorQuery() // create SelectorQuery
      .select('#my-id') // Specify the selector of the target node
      .invoke({
        // Specify the operation for the target node
        method: 'boundingClientRect',
        success: function (res) {
          console.log(res);
        },
        fail: function (res) {
          console.log(res.code, res.data);
        },
      })
      .exec(); // Execute the query
  }, []);

  return (
    <view>
      <text id="my-id">Hello, ReactLynx</text>
    </view>
  );
}
```

[`SelectorQuery`]: /api/lynx-api/selector-query.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.createSelectorQuery`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:**  Create a `SelectorQuery` with the root node of the page as the root.




---
url: /api/lynx-api/lynx/lynx-get-element-by-id.md
---

# getElementById()

<APISummary />

## Introduction

getElementById is a method for finding elements' reference based on a specified id in the current [page](/guide/spec.md#page).
This method takes an id selector as the parameter and returns a reference to the corresponding element's reference.
Please note that this reference does not allow background threads to hold the elements;
background threads can only use this reference to [inter thread call](/guide/spec.md#inter-thread-call-or-itc) [element methods](/guide/spec.md#element-method) across threads,
and this reference does not affect the element's lifecycle.

## Syntax

```js
let element = lynx.getElementById(id);
```

### Parameter

#### id

A String type, the id selector of the element to be obtained.

### Return Value

Returns a NodeRef: If the corresponding element is found, a reference to the element is returned; if no corresponding element is found, null is returned.

## Example

```js
let ele = lynx.getElementById('id');
```

::: tip

The reasons that `getElementById` may not select nodes are:

- The ID selector is incorrect
- The value of the ID selector depends on complex JS expressions, so that the value of the ID selector cannot be obtained at the first screen. At this time, if getElementById is too early (such as in ComponentDidMount), it may not find the node

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getElementById`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Used to import modules.




---
url: /api/lynx-api/lynx/lynx-get-js-module.md
---

# lynx: getJSModule() static method

<APISummary />

Acquire a JavaScript value that can be shared within a single LynxView, but not between different LynxViews.

## Syntax

```ts
getJSModule: <Module>(name: string) => Module;
```

### Parameters

#### name

The name of the value that registered using [`lynx.registerModule`].

### Return Value

The registered value.

If the `name` is not registered, return `undefined`.

## Examples

### Get module from JS

Use the [`lynx.registerModule`] method to register a value:

```js
const fooModule = {};
lynx.registerModule('foo', fooModule);
lynx.getJSModule('foo') === fooModule; // true
```

[`lynx.registerModule`]: /api/lynx-api/lynx/lynx-register-module.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getJSModule`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.4 | - |
| iOS | 2.4 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/lynx/lynx-get-text-info.md
---

# getTextInfo()

<APISummary />

Used to measure the width of text content.

## Syntax

```ts
export interface TextInfo {
  fontSize: string;
  fontFamily?: string;
  maxWidth?: string;
  maxLine?: number;
}

export interface TextMetrics {
  width: number;
  content:  Array<string>;
}

getTextInfo(text: string, info: TextInfo): TextMetrics;
```

### Parameters

#### text

The text string to be measured.

#### info

The attribute information set on the text, supports setting fontSize, fontFamily, maxWidth and maxLine, among which fontSize is mandatory, fontSize and maxWidth only support px unit.

### Return Value

The result of text measurement, including width and the text string of each line, the returned width unit is px.

## Example

```ts
// default font family
const { width } = lynx.getTextInfo('text content', { fontSize: '14px' });

const { width } = lynx.getTextInfo('text content', {
  fontSize: '14px',
  fontFamily: 'PingFang SC',
});

const { content } = lynx.getTextInfo('text content', {
  fontSize: '14px',
  fontFamily: 'PingFang SC',
  maxWidth: '100px',
  maxLine: 2,
});
```

::: tip

- It is strongly recommended to check the passed parameters, data not expected should be filtered out to reduce unexpected time consumption. For example, fontSize is 0, 1, these data with no actual meaning, maxWidth is 0, 1, 2, these data are too small.

- fontFamily currently only supports built-in fonts, does not support custom fonts set through font-face, use the default font when fontFamily is not set.

- Does not currently support letterSpacing, fontWeight and other properties that are not explicitly declared supported.

- If maxLine is set to 1, the returned TextMetrics will not contain content, at this time the transmission of content is meaningless, avoid one transmission overhead.

- In case of non-compliant input, such as `maxLine > 1 && maxWidth < 1` or `fontSize <= 0` or textContent is empty, it will return `TextMetrics {width: 0}`.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getTextInfo`

**Status:** 🧪 Experimental

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Used to measure the width of text content.




---
url: /api/lynx-api/lynx/lynx-global-props.md
---

# GlobalProps

<APISummary />

`lynx.__globalProps` is a global object that you can access from anywhere.

- It is read-only in the front-end code, you cannot modify its value.
- The client can set and update its value by calling APIs provided by the Lynx SDK.
- Every time the client performs an update, it will trigger the `onGlobalPropsChanged` event, followed by a re-rendering of the entire page.

## Usage

```tsx
// The properties within the `lynx.__globalProps` object are not managed by Lynx itself.
// Therefore, you must extend its interface yourself.
declare module '@lynx-js/types' {
  interface GlobalProps {
    appTheme: string;
    title: string;
  }
}

function App() {
  const themeClass = useMemo(
    () => `theme-${lynx.__globalProps.appTheme}`,
    [lynx.__globalProps.appTheme],
  );

  return (
    <view class={themeClass}>
      <text>{lynx.__globalProps.title}</text>
    </view>
  );
}
```

## Event Listening

You can listen for changes to `__globalProps` in your component.

```tsx
import { useLynxGlobalEventListener } from '@lynx-js/react';

export function App() {
  useLynxGlobalEventListener('onGlobalPropsChanged', () => {
    console.log('onGlobalPropsChanged', lynx.__globalProps);
  });

  return <view />;
}
```

## Client side

`__globalProps` can be updated through APIs provided by `LynxView`.

### Android

```java
void updateGlobalProps(@NonNull Map<String, Object> props)

void updateGlobalProps(@NonNull TemplateData props)

```

### iOS

```objc
- (void)updateGlobalPropsWithDictionary:(NSDictionary<NSString*, id>*)data

- (void)updateGlobalPropsWithTemplateData:(LynxTemplateData*)data
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.globalProps`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** global data set by client.




---
url: /api/lynx-api/lynx/lynx-performance.md
---

# lynx: performance readonly object

<APISummary />

This object provides access to performance metrics related to the current page.

## Instance Methods

[`createObserver()`](/api/lynx-api/lynx/lynx-performance/create-observer.md) Creates a [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md) object that will be used to receive performance events generated by Lynx engine.

[`profileStart()`](/api/lynx-api/lynx/lynx-performance/profile-start.md) Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

[`profileEnd()`](/api/lynx-api/lynx/lynx-performance/profile-end.md) Marks the end of the most recent [trace event](https://perfetto.dev/docs/instrumentation/track-events).

[`profileMark()`](/api/lynx-api/lynx/lynx-performance/profile-mark.md) Marks an instant(point-in-time) event.

[`profileFlowId()`](/api/lynx-api/lynx/lynx-performance/profile-flow-id.md) Generates a unique flow id for [flow events](https://perfetto.dev/docs/instrumentation/track-events#flows).

[`isProfileRecording()`](/api/lynx-api/lynx/lynx-performance/is-profile-recording.md) Checks if trace recording is currently active.

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/create-observer.md
---

<APISummary />

Creates a
[`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md)
object that will be used to receive performance events generated by Lynx engine.

#### Syntax

```ts
createObserver(callback: PerformanceCallback): PerformanceObserver;
```

#### Parameters

##### callback

A callback function that handles performance events, defined as `type PerformanceCallback = (entry: PerformanceEntry) => void`. The entry is a subclass of [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md).

This callback is triggered when the [PerformanceObserver](/api/lynx-api/performance-api/performance-observer.md) receives a performance event.

#### Return Value

A `PerformanceObserver` object.

#### Examples

The following example creates a `PerformanceObserver` watching for [`metric.fcp`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`pipeline`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) entries.

**This is an example below:  performance-api**

**Entry:** `src/simple-observe`
```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function SimpleObserveExample(this: any) {
  const [receivedEntries, setReceivedEntries] = useState<Set<string>>(new Set<string>());

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fcp") {
        entryType = "MetricFcpEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["metric.fcp", "pipeline"]);
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver</text>
      </view>
      <view className="card">
        <text className="section-title">Received PerformanceEntry:</text>
        <view className="entries-container">
          {Array.from(receivedEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<SimpleObserveExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/is-profile-recording.md
---

<APISummary />

Checks if trace recording is currently active.

#### Syntax

```typescript
isProfileRecording(): boolean
```

#### Return Value

Return `true` if trace recording is currently active;

### Examples

```typescript
if (lynx.performance.isProfileRecording()) {
  lynx.performance.profileMark('RecordingIsActive');
}
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-end.md
---

<APISummary />

Marks the end of the most recent [trace
event](https://perfetto.dev/docs/instrumentation/track-events).

#### Syntax

```typescript
profileEnd(): void;
```

#### Examples

```typescript
// End the most recent duration event
lynx.performance.profileEnd();
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-flow-id.md
---

<APISummary />

Generates a unique flow id for [flow
events](https://perfetto.dev/docs/instrumentation/track-events#flows).

#### Syntax

```typescript
profileFlowId(): number;
```

#### Return Value

A unique flow id number.

### Examples

```typescript
const flowId = lynx.performance.profileFlowId();
lynx.performance.profileStart('UserAction', { flowId });
lynx.performance.profileMark('ActionCheckpoint', { flowId });
lynx.performance.profileEnd();
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-mark.md
---

<APISummary />

Marks an instant(point-in-time) event.

#### Syntax

```typescript
profileMark(name: string, option?: { flowId: number, arg?:  Record<string, string>}): void;
```

#### Parameters

##### name

The name of the instant event.

##### option(optional)

Additional options such as `flowId` and custom arguments.

#### Examples

```typescript
// Mark an instant event with only a name
lynx.performance.profileMark('FetchStarted');

// Mark an instant event with custom arguments
lynx.performance.profileMark('FetchStarted', {
  args: { status: 'initiated' },
});

// Mark an instant event with a flow id
const flowId = lynx.performance.profileFlowId();
lynx.performance.profileMark('ActionCheckpoint', { flowId });

// Mark an instant event with both arguments and flow id
lynx.performance.profileMark('ProcessMidpoint', {
  args: { step: 'middle' },
  flowId,
});
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-start.md
---

<APISummary />

Marks the start of a [trace
event](https://perfetto.dev/docs/instrumentation/track-events).

#### Syntax

```typescript
profileStart(name: string, option?: { flowId: number, arg?:  Record<string, string>}): void;
```

#### Parameters

##### name

The name of the trace event.

##### option(optional)

Additional options such as `flowId` and custom arguments.

#### Examples

```typescript
// Start a trace event with only a name
lynx.performance.profileStart('DataFetch');

// Start a trace event with custom arguments
lynx.performance.profileStart('DataFetch', {
  args: { url: 'https://api.example.com/data', method: 'GET' },
});

// Start a trace event with a flow id
const flowId = lynx.performance.profileFlowId();
lynx.performance.profileStart('UserAction', { flowId });

// Start a duration event with both arguments and flow ID
lynx.performance.profileStart('ComplexProcess', {
  args: { step: 'start' },
  flowId,
});
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-queue-microtask.md
---

# lynx: queueMicrotask() static method

<APISummary />

Send a task to a microtask queue for execution. For more information about microtask, please refer to [here](https://developer.mozilla.org/en-US/docs/Web/API/Window/queueMicrotask)

## Syntax

```ts
queueMicrotask(callback: () => void): void;
```

### Parameters

#### callback

Function object that needs to be sent to the microtask queue.

### Return Value

None（`undefined`）。

## Examples

```tsx
lynx.queueMicrotask(() => {
  console.log('microtask execute.');
});
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.queueMicrotask`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** insert a task into microtask queue




---
url: /api/lynx-api/lynx/lynx-register-module.md
---

# lynx: registerModule() static method

<APISummary />

Register a JavaScript value that can be shared within a single LynxView, but not between different LynxViews.

## Syntax

```ts
registerModule: <Module>(name: string, module: Module) => void;
```

### Parameters

#### name

The name of the value.

#### module

The value to be registered, can use any JavaScript types.

### Return Value

None (`undefined`).

## Examples

### Get module from JS

Use the [`lynx.getJSModule`] method to get a registered value:

```js
const fooModule = {};
lynx.registerModule('foo', fooModule);
lynx.getJSModule('foo') === fooModule; // true
```

[`lynx.getJSModule`]: /api/lynx-api/lynx/lynx-get-js-module.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.registerModule`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.4 | - |
| iOS | 2.4 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/lynx/lynx-reload.md
---

# lynx: reload() static method

<APISummary />

Reloads the current page, like the Refresh button.

## Syntax

```ts
reload(value: object, callback: () => void): void;
```

### Parameters

#### value

The new initial data the page reloading uses.

#### callback

The callback function when page reloading finishes.

### Return Value

None(`undefined`).

## Notices

1. The `lynx.reload()` method will not trigger the frontend `DataProcessor` function;
2. `__globalProps`, `SystemInfo` and JS global variables will remain unchanged;
3. `lynx.reload()` will trigger the `componentWillUnmount`/`onDetach` callbacks of all current frontend components; and recreate new custom components.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.reload`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.7 | ReactLynx 3.0 is not supported.; ⚠️ Partial implementation |
| iOS | 2.7 | ReactLynx 3.0 is not supported.; ⚠️ Partial implementation |
| HarmonyOS | 3.4 | ReactLynx 3.0 is not supported.; ⚠️ Partial implementation |
| Web | ❌ No | - |

**Description:** Reloads the current page, like the Refresh button.




---
url: /api/lynx-api/lynx/lynx-report-error.md
---

# lynx: reportError() static method

<APISummary />

The `lynx.reportError` method is used to manually report an error from JavaScript.

## Syntax

```ts
reportError(error: string | Error, options?: {level: 'warning' | 'error' | 'fatal'}): void;
```

### Parameters

#### error

`lynx.reportError` the first arg can receive a string or a JavaScript Error object. The second arg can receive an object with a `level` property,where `level` indicates the level of the error, with the `fatal` level interrupting the execution environment to prevent further chaining of errors.

If a string is passed, `reportError` will construct an error object with `JSON.stringify(error)` as the message.

Which means

```js
lynx.reportError('foo');
```

is equivalent with

```js
lynx.reportError(new Error('foo'));
```

### Return Value

None (`undefined`).

## Examples

```tsx
try {
  const { data } = JSON.parse(content);
} catch (error) {
  lynx.reportError(error);
}
```

### Async error with original stack

A common use case is when an exception occurs in an asynchronous callback:

```javascript
import fetch from '@fetch';

export function getData(params) {
  return new Promise((resolve, reject) => {
    fetch(
      {
        url: HOST,
        method: 'GET',
        params,
      },
      function cb(res) {
        if (res?.status_code === 0) {
          lynx.reportError('fetch error: ' + res?.status_code);
          reject(res);
        } else {
          resolve(res);
        }
      },
    );
  });
}
```

But this will result in an error stack like this:

```
at Lynx.reportError (file://shared/lynx_core.js:9821:48)
at cb (file://view/app-service.js:284:27)
```

This first frame points to the `lynx.reportError` method and the second frame points to the callback passed to `fetch`. No more information could be found from the error stack. We could never know who calls the `getData` method from the reported error stack.

This is because Lynx uses polyfilled `Promise` and does not track asynchronous call stacks.
To get a readable error stack, we could construct an error object before entering asynchronous process.

```javascript
import fetch from '@fetch';

export function getData(params) {
  const error = new Error(); // construct the error synchronously
  return new Promise((resolve, reject) => {
    fetch(
      {
        url: 'HOST',
        method: 'GET',
        params,
      },
      (res) => {
        if (res?.status_code === 0) {
          error.message = 'fetch error: ' + res?.status_code;
          lynx.reportError(error);
          reject(res);
        } else {
          resolve(res);
        }
      },
    );
  });
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.reportError`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Used to report a JavaScript Error.




---
url: /api/lynx-api/lynx/lynx-request-animation-frame.md
---

# requestAnimationFrame()

<APISummary />

Invoke the specified callback function at the next VSYNC.

`requestAnimationFrame` is typically used in scenarios where you want to achieve animation effects by modifying element attributes in each frame.
Note that `requestAnimationFrame` will only take effect in the next frame; if you want it to continue to take effect, you need to nest `requestAnimationFrame`.

## Syntax

```ts
requestAnimationFrame: (callback: (timeStamp: number) => void) => number;
```

### Parameters

#### callback

The callback function that needs to be called at the next VSYNC.
The callback function has one parameter `timeStamp`, which is the moment when the callback function starts to execute.

### Return Value

An integer type id, used to cancel this `requestAnimationFrame` callback.

## Examples

Print the frame rate in the console:

**This is an example below:  lynx-api**

**Bundle:** `dist/request-animation-frame.lynx.bundle` | Web: `dist/request-animation-frame.web.bundle`

```tsx
import { root, useEffect, useRef, useState } from "@lynx-js/react";

import "./index.css";

import arrow from "../../resource/arrow.png";
import lynxLogo from "../../resource/lynxlogo.png";

const RequestAnimationFrame = () => {
  const lastUptimeRef = useRef(0);
  const framesRef = useRef(0);
  const [fpsStr, setFpsStr] = useState("0");

  function drawFrame(timestamp: number) {
    requestAnimationFrame(drawFrame);
    framesRef.current++;
    const time = Math.floor(timestamp / 3000) | 0;

    if (time !== lastUptimeRef.current) {
      setFpsStr(String(Math.floor(framesRef.current / 3)));
      console.log("FPS: " + fpsStr);
      lastUptimeRef.current = time;
      framesRef.current = 0;
    }
  }
  useEffect(() => {
    requestAnimationFrame(drawFrame);
  }, []);
  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo">
            <image src={lynxLogo} className="Logo--lynx" />
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">{"FPS: " + fpsStr}</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
};

root.render(<RequestAnimationFrame />);

```



## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requestAnimationFrame`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Invoke the specified callback function at the next VSYNC.




---
url: /api/lynx-api/lynx/lynx-request-resource-prefetch.md
---

# lynx: requestResourcePrefetch() static method

<APISummary />

- This API is used for proactively initiating the preloading of CDN resources from the frontend, currently supporting only **image**, **video**, and **audio** resource types.
- The preloaded resources will not be returned to the frontend through this API; instead, they are retained in memory or on disk. Therefore, after preloading is complete, a `unique key` is needed to specify the resource to the component:
  - The key for an image resource is consistent with the `uri` parameter during its preloading. When rendering, pass this key to the [src](/api/elements/built-in/image.md#src) attribute of the `<image />` component, allowing the component to locate the resource.

## Syntax

```ts
requestResourcePrefetch(data: object, callback: (res: object) => void) : void;
```

### Parameters

#### `data`

A collection that describes all the details of the resources to be preloaded, its keys are defined as follows:

- `data`: Type `array`, each item inside the array corresponds to a resource. The keys for each item are defined as follows:
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of resource. The defined types of resources are as follows:
    - `image`: Image resource. (api/elements/built-in/image.html#trailnewimage--) switch for the Image component to preload images.)
    - `video`: Video resource.
    - `audio`: Audio resource.
  - `params` (optional): Custom control parameters for resource preloading, the supported parameters are as follows:
    - `priority` (optional): Only for `image` type resources. Indicates network request priority. If the priority is high, other image requests will be blocked while the image library preloads these images, which may slow down the display of other images. Therefore, if these preloaded images are not immediately needed for display, consider setting a lower priority. The options supported are as follows:
      - `high`: High priority.
      - `medium`: Medium priority.
      - `low`: Low priority, this is the default value.
    - `cacheTarget` (optional): Only for `image` type resources. Indicates the form in which resources are saved. The options supported are as follows:
      - `disk`: Resource is saved to disk after preloading is completed, this is the default value.
      - `bitmap`: Resource is decoded into a bitmap and saved in memory after preloading. (**Note: Currently, Android bitmap caching is not yet effective.**)
    - `preloadKey`: Only for `video`, `audio` type resources. Represents a unique key that identifies the resource. When rendering the \<x-video-pro> component, this key must be specified so that the component can find the preloaded cache. This is a required parameter.
    - `size` (optional): Only for `video` type resources. Indicates the size of the preload, with a default value of 500 \* 1024 (bytes).

#### `callback`

The callback function called after the API is executed or fails. The inside definition of its parameters is as follows:

- `code`: Type `number`, status code, which may take the following values:
  - `0`: Success.
  - `11001`: Parameter error.
- `msg`: Type `string`, a global error message.
- `details`: Type `array`, where each detail represents the preload status details of a resource, with the internal definition of detail as follows:
  - `code`: Type `number`, status code, which may take the following values:
    - `0`: Success.
    - `11001`: Parameter error.
  - `msg`: Type `string`, error message.
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of the resource, with resource types defined as follows:
    - `image`: Image resource.
    - `video`: Video resource.
    - `audio`: Audio resource.

### Return Value

None (`undefined`).

## Errors

- When there is a parameter error, the `code` will return the `11001` error code, and the `msg` will contain detailed error information.

## Example

```js
import { useState, useEffect } from '@lynx-js/react';

function Page() {
  const [show, setShow] = useState(false);

  useEffect(() => {
    // We initiate resource preloading ahead of time when the page DidMount
    // We need to preload a batch of resources, including two images and two videos.
    // First, prepare the resource parameters, assign priority and cacheTarget for images, and the required preloadKey for videos.
    let resData = [
      {
        uri: 'https://xxxxx1.jpg',
        type: 'image',
        params: { priority: 'high', cacheTarget: 'disk' },
      },
      {
        uri: 'https://xxxxx2.jpg',
        type: 'image',
        params: { cacheTarget: 'bitmap' },
      },
      {
        uri: 'https://zzzzz1.mp4',
        type: 'video',
        params: { preloadKey: 'zzzzz1' },
      },
      {
        uri: 'https://zzzzz2.mp4',
        type: 'video',
        params: { preloadKey: 'zzzzz2' },
      },
    ];

    // Call the requestResourcePrefetch to initiate preloading
    lynx.requestResourcePrefetch?.(
      {
        data: resData,
      },
      (res) => {
        if (res.code == 0) {
          console.log('success!');
        } else {
          console.log('fail! ', res.msg);
        }
        console.log(
          'prefetch status of each resource:',
          JSON.stringify(res.details),
        );
      },
    );
  }, []);

  const handleTap = () => {
    // Change the show state through setState to control the display of images and videos
    setShow(!show);
  };

  return (
    <view onTap={handleTap}>
      {/* According to the show status to determine whether to display the image, note that here src is the unique key mentioned above, this should keep the src consistent with the preload time */}
      {show && <image src="https://xxxxx1.jpg" />}
      {show && <image src="https://xxxxx2.jpg" />}
      {/* According to the show status to determine whether to display the video, note that here preload-key is the unique key mentioned above, this should keep the preload-key consistent with the preload time */}
      {show && <x-video-pro src="https://zzzzz1.mp4" preload-key="zzzzz1" />}
      {show && <x-video-pro src="https://zzzzz2.mp4" preload-key="zzzzz2" />}
    </view>
  );
}

export default Page;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requestResourcePrefetch`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.6 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to request the prefetch of resource.




---
url: /api/lynx-api/lynx/lynx-require-module-async.md
---

# lynx: requireModuleAsync() static method

<APISummary />

Used to import modules. Just like the [`requireModule`](/api/lynx-api/lynx/lynx-require-module.md) method, but loading asynchronously.

During the loading, the other JavaScript code can be executed.

The module loaded by `requireModuleAsync` needs to use a specific format. Use [`@lynx-js/runtime-wrapper-webpack-plugin`](https://www.npmjs.com/package/@lynx-js/runtime-wrapper-webpack-plugin) to generate modules that are `requireModuleAsync`-loadable.

## Syntax

```ts
requireModuleAsync<T>(path: string, callback: (error: Error | null, exports?: T) => void): void;
```

### Parameters

#### path

The path of the module. Can be a remote path, or a path inside the template.

#### callback

The callback to be executed after the require is finished

- If any error occurs, an error will be passed as the first parameter.
- Otherwise, a `null` will be passed as the first parameter, and the exported value of the module will be passed as the second parameter.

### Return Value

None (`undefined`).

## Exception

`requireModuleAsync` will return an error in callback when:

- Network error
- Module execute error

## Examples

### Loading remote resources

```tsx
lynx.requireModuleAsync('https://example.com/path/to/chunk', (err, exports) => {
  if (err) {
    return;
  }
  // use exports
});
```

### Promisify

```js
const requireModulePromise = (path) =>
  new Promise((resolve, reject) => {
    lynx.requireModuleAsync(path, (err, exports) => {
      if (err) {
        return reject(err);
      }
      return resolve(exports);
    });
  });

await requireModulePromise('path/to/chunk');
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requireModuleAsync`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Used to import modules.




---
url: /api/lynx-api/lynx/lynx-require-module.md
---

# lynx: requireModule() static method

<APISummary />

Used to import modules. Just like NodeJS's [`require`](https://nodejs.org/docs/latest/api/modules.html#requireid).

`requireModule` will load the module **synchronously**. During the loading, the JavaScript thread will be hang. No JavaScript code will be executed.

## Syntax

```ts
requireModule<T>(path: string): T;
```

### Parameters

#### path

The path of the module. Can be a remote path, or a path inside the template.

### Return Value

The exported value of the module.

## Exception

`requireModule` will throw an exception when:

- Network error
- Module execute error
- Timeout

The error can be catch and handled by using `try-catch`.

### Timeout

To avoid JavaScript thread hang forever when loading remote resources, `requireModule` will throw an exception 5 seconds after the request is sent.

## Examples

### Loading remote resources

```tsx
const foo = lynx.requireModule('https://example.com/path/to/chunk');
```

### Re-try on timeout

```js
let result = null;
(function () {
  let retry = 0;
  function requireModule(path) {
    try {
      result = lynx.requireModule(path);
    } catch (error) {
      retry += 1;
      if (retry < 3) {
        requireModule(path);
      } else {
        throw error;
      }
    }
  }
  requireModule('path/to/chunk');
})();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requireModule`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Used to import modules and JSON.




---
url: /api/lynx-api/lynx/lynx-resume-exposure.md
---

# lynx: resumeExposure() static method

<APISummary />

The `lynx.resumeExposure` method can be used to turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.

## Syntax

```ts
resumeExposure(): void;
```

### Parameters

None (`undefined`).

### return value

None (`undefined`).

## Precautions

Calling `lynx.resumeExposure` may not trigger an exposure event. Whether or not an exposure event is triggered depends on the difference between the results of this exposure detection and the previous one. For details, please refer to [Exposure Capability](/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.resumeExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.




---
url: /api/lynx-api/lynx/lynx-set-observer-frame-rate.md
---

# lynx: setObserverFrameRate() static method

<APISummary />

The `lynx.setObserverFrameRate` method can be used to set the frequency of exposure detection.

## grammar

```ts
setObserverFrameRate(options?: Options): void;
```

### Parameters

#### options

```ts
interface Options {
  forPageRect?: number;
  forExposureCheck?: number;
}
```

Specify exposure detection frequency:

- `forPageRect`: unit `fps`, specifies the minimum time interval for detecting `LynxView` position changes. Defaults to 20.
- `forExposureCheck`: unit `fps`, specifies the minimum time interval for detecting the visibility of the target node. Defaults to 20.

### return value

None (`undefined`).

### Precautions

When `LynxView` will not have position changes, such as full-page scenarios, you can set `forPageRect` to `0` to stop detecting position changes of `LynxView`. However, in the card scene, setting `forPageRect` to `0` will cause the exposure of the `Lynx` card to fail in the sliding scene. For details, please refer to [Exposure Ability](/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.setObserverFrameRate`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.15 | - |
| iOS | 2.15 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Set the frequency of exposure detection.




---
url: /api/lynx-api/lynx/lynx-stop-exposure.md
---

# lynx: stopExposure() static method

<APISummary />

The `lynx.stopExposure` method can be used to stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future. You can call \[lynx.resumeExposure]\(./lynx-resume-exposure .mdx) to restart exposure detection.

## Syntax

```ts
stopExposure(options?: StopExposureOptions): void;
```

### Parameters

#### options

```ts
interface StopExposureOptions {
  sendEvent?: boolean;
}
```

Specify the behavior of `lynx.stopExposure`:

- `sendEvent`: Specify whether to send anti-exposure events of all currently visible target nodes. Defaults to `true`.

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.stopExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future.




---
url: /api/lynx-api/main-thread.md
---

# Main Thread APIs

<APISummary />

Main Thread Script allows JavaScript scripts to be executed on the main thread.

Main Thread Scripts are commonly used for smooth animations and gesture handling. They address the response delay issue caused by events being triggered and handled on different threads in the Lynx multi-threaded architecture, thereby achieving a near-native interactive experience.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.main-thread.MainThread-APIs`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** APIs available on the main thread.




---
url: /api/lynx-api/main-thread/element-get-computed-style.md
---

# getComputedStyleProperty()

<APISummary />

## Introduction

The **`getComputedStyleProperty()`** method of the [`Element`](/api/lynx-api/main-thread/main-thread-element.md) returns the [computed style](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#resolved_value) for the element.

## Syntax

```ts
const value = element.getComputedStyleProperty(styleName);
```

### Parameters

#### styleName

A string specifying the property name to be retrieved. The style name must be in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case).

### Return Value

A string containing the value of the [computed style](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#resolved_value).

## Example

```ts
const width = element.getComputedStyleProperty('width');
const backgroundColor = element.getComputedStyleProperty('background-color');
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.main-thread.ElementGetComputedStyle`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |
| HarmonyOS | 3.5 | - |
| Web | ❌ No | - |

**Description:** Create An Animation in MTS




---
url: /api/lynx-api/main-thread/lynx-animate-api.md
---

# animate()

<APISummary />

## Introduction

Use `animate()` to set a [CSS Animation](/api/css/properties/animation.md) on UI elements.

## Syntax

```js
animate(keyframes, options);
```

### Parameter

#### keyframes

1. An **array** consisting of objects that contain properties and values of multiple keyframes.

```js
function controlAnimation(ele: MainThread.Element) {
  'main thread'
  ele.animate(
    [
      {
        // from
        opacity: 0,
        color: '#fff',
      },
      {
        // to
        opacity: 1,
        color: '#000',
      },
    ],
    2000,
  );
}
```

2. Assign a [timing-function](/api/css/properties/animation-timing-function.md) for each keyframe to control the animation's speed.

```js
function controlAnimation(ele: MainThread.Element) {
  'main thread'
  ele.animate(
    [
      {
        // from
        opacity: 0,
        color: '#fff',
        'animation-timing-function': 'linear',
      },
      {
        // to
        opacity: 1,
        color: '#000',
        'animation-timing-function': 'ease-in',
      },
    ],
    2000,
  );
}
```

#### options

An **object** that contains one or more properties:

| Key        | Value Type | Optional | Description                                                                                                                                                                                                                                                                        | Default Value          |
| ---------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| duration   | Number     | optional | The length of time for the animation to run.                                                                                                                                                                                                                                       | 0                      |
| delay      | Number     | optional | The length of time to wait before starting the animation.                                                                                                                                                                                                                          | 0                      |
| iterations | Number     | optional | The number of times the animation should repeat. You can set this to `Infinity` to make the animation loop indefinitely.                                                                                                                                                           | 1                      |
| direction  | String     | optional | Whether the animation runs forwards (`normal`), backwards (`reverse`), switches direction after each iteration (`alternate`), or runs backwards and switches direction after each iteration (`alternate-reverse`). Defaults to `"normal"`.                                         | `"normal"`             |
| easing     | String     | optional | The rate of the animation's change over time. Accepts an [timing-function](/api/css/properties/animation-timing-function.md), such as `"linear"`, `"ease-in"`, or `"cubic-bezier(0.42, 0, 0.58, 1)"`. Defaults to "linear".                                                        | `"linear"`             |
| fill       | String     | optional | Dictates whether the animation's effects should be reflected by the element(s) prior to playing ("backwards"), retained after the animation has completed playing ("forwards"), or both. Defaults to "none".                                                                       | `"none"`               |
| name       | String     | optional | The name of the animation, which can be used to uniquely identify it. This name appears in the [animation events](/api/lynx-api/event/animation-event.md#animation) parameters and is typically used to determine if a particular animation event is the one you're interested in. | An internal unique ID. |
| play-state | String     | optional | Animation motion state, which defines whether an animation is running or paused, accepts an [animation-play-state](/api/css/properties/animation-play-state.md)                                                                                                                    | running                |

:::info Note:

If no `name` is specified, a unique id is generated incrementally.

:::

### Return Value

Returns an `Animation` object.
The `Animation` object has the following methods:

| Method Name          | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `Animation.cancel()` | Cancels the animation and triggers the `animation cancel` event. |
| `Animation.pause()`  | Pauses the animation.                                            |
| `Animation.play()`   | Resumes the animation.                                           |

## Example

```js
function controlAnimation(ele: MainThread.Element) {
  'main thread'
  let ani = ele.animate(
    [
      {
        'background-color': 'blue',
        transform: 'translateX(100px) translateY(300px) rotate(360deg)',
      },
      {
        'background-color': 'red',
        transform: 'translateX(0px) translateY(600px) rotate(0deg)',
      },
    ],
    {
      duration: 3000,
      delay: 1000,
      iterations: Infinity,
      direction: 'alternate',
      easing: 'ease-in-out',
      fill: 'both',
    },
  );

  ani.pause();
  ani.play();
  ani.cancel();
}

```

## Animation Event

The events for the `animate()` API are the same as the [animation events](/api/lynx-api/event/animation-event.md#animation) for CSS animations.

## See also

- [Introduction to CSS Animations](/guide/styling/animation.md)
- [Animate API in BTS](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.main-thread.ElementAnimate`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Create An Animation in MTS




---
url: /api/lynx-api/main-thread/lynx-get-text-info.md
---

<GetTextInfo />



---
url: /api/lynx-api/main-thread/lynx-global-props.md
---

<GlobalProps />



---
url: /api/lynx-api/main-thread/lynx-query-select-all.md
---

# lynx: querySelectorAll(selector: string)

<APISummary />

Find all elements within the page's child elements that match the specified selector.

## Syntax

```ts
const elementArray = lynx.querySelectorAll(selector);
```

### Parameters

#### selector

For a list of supported selectors, see [selector](/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

[`MainThread.Element[]`](/api/lynx-api/main-thread/main-thread-element.md) or `[]`。

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.querySelectorAll`

**Status:** 🧪 Experimental

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/main-thread/lynx-query-selector.md
---

# lynx: querySelector(selector: string)

<APISummary />

Find the first element within the page's child elements that matches the specified selector.

## Syntax

```ts
const element = lynx.querySelector(selector);
```

### Parameters

#### selector

For a list of supported selectors, see [selector](/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

[`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md) or `null`。

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.querySelector`

**Status:** 🧪 Experimental

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/main-thread/lynx-request-animation-frame.md
---

<RAF />



---
url: /api/lynx-api/main-thread/lynx-resume-exposure.md
---

# lynx: resumeExposure() static method

<APISummary />

The `lynx.resumeExposure` method can be used to turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.

## Syntax

```ts
resumeExposure(): void;
```

### Parameters

None (`undefined`).

### return value

None (`undefined`).

## Precautions

Calling `lynx.resumeExposure` may not trigger an exposure event. Whether or not an exposure event is triggered depends on the difference between the results of this exposure detection and the previous one. For details, please refer to [Exposure Capability](/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.resumeExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.




---
url: /api/lynx-api/main-thread/lynx-stop-exposure.md
---

# lynx: stopExposure() static method

<APISummary />

The `lynx.stopExposure` method can be used to stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future. You can call \[lynx.resumeExposure]\(./lynx-resume-exposure .mdx) to restart exposure detection.

## Syntax

```ts
stopExposure(options?: StopExposureOptions): void;
```

### Parameters

#### options

```ts
interface StopExposureOptions {
  sendEvent?: boolean;
}
```

Specify the behavior of `lynx.stopExposure`:

- `sendEvent`: Specify whether to send anti-exposure events of all currently visible target nodes. Defaults to `true`.

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.stopExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future.




---
url: /api/lynx-api/main-thread/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.




---
url: /api/lynx-api/nodes-ref.md
---

# NodesRef

<APISummary />

Represents a reference to one or more UI nodes. It can be used to invoke UI methods, get and set properties on UI nodes.

`NodesRef` only saves the information needed to find nodes (such as CSS selectors), and does not actually reference a specific node.
The actual node search is only carried out when `SelectorQuery.prototype.exec()` is executed.
Therefore, the node that `NodesRef` reference may not actually exist. In this case, an error will be reported when `exec()` is called.

## Instance Method

[`NodesRef.fields()`](/api/lynx-api/nodes-ref/nodes-ref-fields.md)

Query the attributes of the selected node.

[`NodesRef.invoke()`](/api/lynx-api/nodes-ref/nodes-ref-invoke.md)

Execute the UI method of the selected node.

[`NodesRef.path()`](/api/lynx-api/nodes-ref/nodes-ref-path.md)

Query the path information from the node to the root node of the page.

[`NodesRef.setNativeProps()`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md)
.mdx)

Directly set the attributes of the selected node.

## Examples

Obtain the position and size of the specified `text` node:

```tsx
class Page extends Component {
  componentDidMount() {
    lynx
      .createSelectorQuery() // create SelectorQuery
      .select('#my-id') // Specify the selector of the target node
      .invoke({
        // Specify the operation for the target node
        method: 'boundingClientRect',
        success: function (res) {
          console.log(res);
        },
        fail: function (res) {
          console.log(res.code, res.data);
        },
      })
      .exec(); // Execute the query
  }

  render() {
    return (
      <view>
        <text id="my-id">...</text>
      </view>
    );
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.NodesRef`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Represents a reference to one or more UI nodes. It can be used to call methods, get and set properties on UI nodes.




---
url: /api/lynx-api/nodes-ref/nodes-ref-fields.md
---

# NodesRef: fields() method

<APISummary />

Query the attributes of the selected node.

## Syntax

```ts
fields(fields: Record<string, boolean>, callback: (data: object, status: object) => void): SelectorQuery;
```

### Parameters

#### fields

A `Record<string, boolean>`, describing whether it is necessary to query the corresponding type of property.
The range of queryable property types is as follows, and values outside this range will be ignored:

- `attribute` (optional)

  - Only custom attributes will be returned, attributes such as `id`, `class`, `style`, `dataset` will not be returned.
  - Attributes with values `null` / `undefined` / `function` will not be returned.
  - The key of the returned value is in kebab case.

- `class` (optional)

- `dataset` (optional)

- `id` (optional)

- `index` (optional)

- `query` (optional)

  - The `SelectorQuery` object with this node as the root node
    - The query performed on this `SelectorQuery` object is limited to this node and its descendant nodes.
    - Calling `selectRoot()` on this `SelectorQuery` object will return the `NodesRef` object representing this node.

- `tag` (optional)

- `unique_id` (optional)

#### callback

A callback function, the query result will be returned as the parameter of the callback function. The callback function has two parameters:

The first parameter returns the query result.

- If the `NodesRef` represents one single node, it returns a `Record<string, any>` object containing the query result. If the node is not found, it returns `null`.
- If the `NodesRef` represents multiple nodes, it returns an array of `Record<string, any>` objects, each element in the array corresponds to the query result of a node. If no nodes are found, it returns an empty array.

The second parameter returns the status of the query (error message).

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

```javascript
lynx
  .createSelectorQuery()
  .select('#id')
  .fields(
    {
      id: true,
      dataset: true,
      tag: true,
    },
    (data, status) => {
      console.log(data, status);
    },
  )
  .exec();
```

Possible output;

```javascript
// data
{"tag":"text","dataset":{"hello":"world"},"id":"my-id"}

// status
{"data":"success","code":0}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.fields`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Query the attributes of the selected node.




---
url: /api/lynx-api/nodes-ref/nodes-ref-invoke.md
---

# NodesRef: invoke() method

<APISummary />

Execute the UI method of the selected node.

Please note that the UI function is a function provided by the client, usually directly controlling UI functions, such as the play or stop of the player.
`invoke` cannot be used to call a js function of a custom component.

## Syntax

```ts
invoke(options: Record<string, any>): SelectorQuery;
```

### Parameters

### options

The `options` parameter is a `Record<string, any>`, which contains the information needed for the execution of the UI method. Its key list is as follows:

- `method`

- A `string`, the name of the UI method to be called

- `params` (optional)

- A `Record<string, any>`, the parameters of the UI method to be called

- `success` (optional)

- A callback function that is called when the UI method is successfully executed, with the first parameter being the result returned by the UI method

- `fail` (optional)

- A callback function that is called when the UI method fails to execute, with the first parameter type being `{code: number, data: any}`, which contains the error code and error message returned by the UI method.

- If no fail callback function is provided, a red screen error will be generated when the UI method fails to execute.

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

```javascript
var params = {
  method: 'seekTo',
  params: {
    duration: 1000,
  },
  success: function (res) {
    console.log(res);
  },
  fail: function (data) {
    console.log(data.code, data.data);
  },
};

lynx.createSelectorQuery().select('#video').invoke(params).exec();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.invoke`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| iOS | 2.2 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| HarmonyOS | 3.4 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| Web | 1.0 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |

**Description:** Execute the UI method of the selected node.




---
url: /api/lynx-api/nodes-ref/nodes-ref-path.md
---

# NodesRef: path() method

<APISummary />

Query the path information from the node to the root node of the page.

## Syntax

```ts
path(callback: (data: object, status: object) => void): SelectorQuery;
```

### Parameters

#### callback

A callback function, the query result will be returned as the parameter of the callback function. The callback function has two parameters:

The first parameter returns the query result.

- If the `NodesRef` represents one single node, it returns a `Record<string, any>` object containing the query result. If the node is not found, it returns `null`.
- If the `NodesRef` represents multiple nodes, it returns an array of `Record<string, any>` objects, each element in the array corresponds to the query result of a node. If no nodes are found, it returns an empty array.

The second parameter returns the status of the query (error message).

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

```javascript
lynx
  .createSelectorQuery()
  .select('#target')
  .path((res, status) => {
    console.log(JSON.stringify(res));
    console.log(JSON.stringify(status));
  })
  .exec();
```

Possible output:

```javascript
// res
{
    // array from target to root
    "path":
    [
        {
            tag:"",
            id:"",
            class:[],
            dataSet:{},
            // index of parent's children
            index:0,
        },
        ...
        {
            tag:"page",
            id:"",
            class:[],
            dataSet:{},
            index:0,
        }
    ]
}

// status
{
  "data": "succeed",
  "code": 0
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.path`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Query the path information from the node to the root node of the page.




---
url: /api/lynx-api/nodes-ref/nodes-ref-set-native-props.md
---

# NodesRef: setNativeProps() method

<APISummary />

Directly set the attributes of the selected node.

:::warning When should you use setNativeProps?
When you have to refresh frequently and encounter performance bottlenecks.

Directly operating components is not a tool that should be used often.
Generally, it is only used to create continuous animations, while avoiding the large overhead brought about by rendering component structures and synchronizing too many view changes.
`setNativeProps` is a "simple and crude" method, it directly records the state at element instead of in the Lynx component, which makes the code logic difficult to understand.
So before using this method, please try to solve the problem with [`useState`](/api/react/Function.useState.md) method first.
:::

## Syntax

```ts
setNativeProps(nativeProps: Record<string, any>): SelectorQuery;
```

### Parameters

#### nativeProps

A `Record<string, any>`, describes the properties that need to be set. Properties can be any attribute of the UI node, including CSS properties and `attributes`.

Note that `style` cannot be set as a whole (the key of `nativeProps` cannot be `style`).

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

1. Set the text content of the text node.

```jsx
function App() {
  return (
    <view
      bindtap={() => {
        lynx
          .createSelectorQuery()
          .select('#intro')
          .setNativeProps({
            text: 'Hello, Lynx!',
          })
          .exec();
      }}
    >
      <text id="intro">Hello, World!</text>
    </view>
  );
}
```

2. Set the `upper-threshold` attribute of `<scroll-view />`.

```jsx
function App() {
  return (
    <scroll-view id="intro">
      <text
        bindtap={() => {
          lynx
            .createSelectorQuery()
            .select('#intro')
            .setNativeProps({
              'upper-threshold': '10px',
            })
            .exec();
        }}
      >
        Hello, World!
      </text>
    </scroll-view>
  );
}
```

3. Set the background color of the `<view />`.

```jsx
function App() {
  return (
    <view id="intro">
      <text
        bindtap={() => {
          lynx
            .createSelectorQuery()
            .select('#intro')
            .setNativeProps({
              'background-color': 'red',
            })
            .exec();
        }}
      >
        Hello, World!
      </text>
    </view>
  );
}
```

4. Modify the transform properties

```jsx
function App() {
  return (
    <view
      bindtap={() => {
        lynx
          .createSelectorQuery()
          .select('#intro')
          .setNativeProps({
            transform: 'translateY(3px)',
          })
          .exec();
      }}
    >
      <text id="intro">Hello, World!</text>
    </view>
  );
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.setNativeProps`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Directly set the attributes of the selected node.




---
url: /api/lynx-api/performance-api/framework-pipeline-timing.md
---

# FrameworkPipelineTiming

<APISummary />

This interface describes the performance data of key stages in [framework rendering](/guide/spec.md#framework-rendering).

## Instance Properties

### dsl

```tsx
dsl: string;
```

A string describing the DSL type, with a default value of `reactlynx`.

### stage

```tsx
stage: string;
```

A string describing the type of framework data update process, with possible values `hydrate` and `update`. `hydrate` refers to the process of calibrating and updating [main thread](/guide/spec.md#main-thread-or-lynx-main-thread) data using [background thread](/guide/spec.md#background-thread-aka-off-main-thread) data, while `update` refers to updates triggered in `useEffect`. For more information, see [ReactLynx Lifecycle](/react/lifecycle.md).

### diffVdomStart

```tsx
diffVdomStart: number;
```

The timestamp when the framework starts VDom Diff on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### diffVdomEnd

```tsx
diffVdomEnd: number;
```

The timestamp when the framework ends VDom Diff on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### packChangesStart

```tsx
packChangesStart: number;
```

The timestamp when the framework starts serializing change information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### packChangesEnd

```tsx
packChangesEnd: number;
```

The timestamp when the framework ends serializing change information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### parseChangesStart

```tsx
parseChangesStart: number;
```

The timestamp when the framework starts deserializing change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### parseChangesEnd

```tsx
parseChangesEnd: number;
```

The timestamp when the framework ends deserializing change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### patchChangesStart

```tsx
patchChangesStart: number;
```

The timestamp when the framework starts applying change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### patchChangesEnd

```tsx
patchChangesEnd: number;
```

The timestamp when the framework ends applying change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### hydrateParseSnapshotStart

```tsx
hydrateParseSnapshotStart: number;
```

The timestamp when the framework starts deserializing [main thread](/guide/spec.md#main-thread-or-lynx-main-thread) information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

:::tip
This property is only valid when `stage` is `hydrate`.
:::

### hydrateParseSnapshotEnd

```tsx
hydrateParseSnapshotEnd: number;
```

The timestamp when the framework ends deserializing [main thread](/guide/spec.md#main-thread-or-lynx-main-thread) information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

:::tip
This property is only valid when `stage` is `hydrate`.
:::

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.framework-pipeline-timing`


---
url: /api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md
---

# AndroidHostPlatformTiming

<APISummary />

This interface describes the performance data specific to Android platform's Measure, Layout, and Draw operations in the [Lynx Pipeline](/guide/spec.md#lynx-pipeline), as shown in the following diagram:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/host-platform-timing.png" />

## Examples

This example shows how to generate and obtain `AndroidHostPlatformTiming`.

**This is an example below:  performance-api**

**Entry:** `src/host-platform-timing`
**Bundle:** `dist/host-platform-timing.lynx.bundle`

```tsx {21-21}
import { root, useEffect, useState } from "@lynx-js/react";
import type { PerformanceEntry, PipelineEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function PipelineEntryExample() {
  const [myName, setMyName] = useState<string | undefined>(undefined);
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [hostPlatformTiming, setHostPlatformTiming] = useState("");

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline" event of "myPipeline".
        const pipelineEntry = entry as PipelineEntry;
        // `PerformanceEntry.identifier` is equal to `view.__lynx_timing_flag`.
        if (pipelineEntry.identifier == "myNamePipeline") {
          setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
          setHostPlatformTiming(JSON.stringify(pipelineEntry.hostPlatformTiming, null, 4));
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMyName("HostPlatformTiming");
    }, 2000);
  }, []);

  return (
    <view className="container">
      <text className="title" __lynx_timing_flag={myName ? "myNamePipeline" : ""}>Hello {myName}~</text>
      <ScrollItem title="HostPlatformTiming" value={hostPlatformTiming} height="220px" />
      <ScrollItem title="PipelineEntry" value={pipelineEntry} />
    </view>
  );
}

root.render(<PipelineEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance Properties

### hostPlatformType

```tsx
hostPlatformType: string;
```

A string describing the Host Platform type, with default value: `Android`.

### measureStart

```tsx
measureStart: number;
```

The timestamp when the first execution of [LynxView](/guide/spec.md#lynxview)'s [onMeasure](https://developer.android.com/reference/android/view/View#onMeasure\(int,%20int\)) starts in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### measureEnd

```tsx
measureEnd: number;
```

The timestamp when the last execution of [LynxView](/guide/spec.md#lynxview)'s [`onMeasure`](https://developer.android.com/reference/android/view/View#onMeasure\(int,%20int\)) ends in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### layoutStart

```tsx
layoutStart: number;
```

The timestamp when the first execution of [LynxView](/guide/spec.md#lynxview)'s [`onLayout`](https://developer.android.com/reference/android/view/View#onLayout\(boolean,%20int,%20int,%20int,%20int\)) starts in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### layoutEnd

```tsx
layoutEnd: number;
```

The timestamp when the last execution of [LynxView](/guide/spec.md#lynxview)'s [`onLayout`](https://developer.android.com/reference/android/view/View#onLayout\(boolean,%20int,%20int,%20int,%20int\)) ends in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### drawStart

```tsx
drawStart: number;
```

The timestamp when the execution of [LynxView](/guide/spec.md#lynxview)'s [`dispatchDraw`](https://developer.android.com/reference/android/view/View#dispatchDraw\(android.graphics.Canvas\)) starts in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### drawEnd

```tsx
drawEnd: number;
```

The timestamp when the execution of [LynxView](/guide/spec.md#lynxview)'s [`dispatchDraw`](https://developer.android.com/reference/android/view/View#dispatchDraw\(android.graphics.Canvas\)) ends in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.host-platform-timing.android-host-platform-timing`


---
url: /api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md
---

# HarmonyHostPlatformTiming

<APISummary />

This interface describes performance data for Harmony platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline).

## Instance Properties

### hostPlatformType

```tsx
hostPlatformType: string;
```

A string describing the Host Platform type, with default value: `Harmony`.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.host-platform-timing.harmony-host-platform-timing`


---
url: /api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md
---

# IOSHostPlatformTiming

<APISummary />

This interface describes performance data for iOS platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline).

## Instance Properties

### hostPlatformType

```tsx
hostPlatformType: string;
```

A string describing the Host Platform type, with default value: `iOS`.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.host-platform-timing.ios-host-platform-timing`


---
url: /api/lynx-api/performance-api/performance-entry.md
---

# PerformanceEntry

<APISummary />

`PerformanceEntry` is a base interface used to describe the complete data of performance events. All performance events inherit from and extend it, commonly including [container](/guide/spec.md#container) initialization, page loading, and rendering times.

All performance events are summarized in the figure below:

<center>
  <img width="60%" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/performance-entry-v3.png" />
</center>

## Instance Properties

### entryType

```tsx
entryType: string;
```

Represents a string indicating the type of `PerformanceEntry`. The currently supported types are: `init`, `metric`, and `pipeline`, with the following meanings:

- **`init`**: Records performance events for the initialization process before the Lynx page is displayed.
- **`metric`**: Records performance metric events, such as FCP (First Contentful Paint), TTI (Time to Interactive), and ActualFMP (Actual First Meaningful Paint).
- **`pipeline`**: Records performance events during the rendering process.
- **`resource`**: Records performance events for resource loading.

The corresponding subclasses for each entryType value are shown in the table below.

|  entryType |                                                                                                                                                    subclasses                                                                                                                                                    |
| :--------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|   `init`   | [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md), [`InitLynxviewEntry`](/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md), [`InitBackgroundRuntimeEntry`](/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md) |
|  `metric`  |                                                           [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md), [`MetricActualfmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md)                                                          |
| `pipeline` |                  [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md), [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md), [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md)                  |
| `resource` |                                                                                                             [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md)                                                                                                            |

### name

```tsx
name: string;
```

A string representing the name of the `PerformanceEntry`. The value depends on the specific type of the `PerformanceEntry` object. The corresponding names for all subtypes are shown in the table below:

|                                                    subclasses                                                    |                                           name                                           |
| :--------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------: |
|          [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md)         |                                        `container`                                       |
|           [`InitLynxviewEntry`](/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md)          |                                        `lynxview`                                        |
| [`InitBackgroundRuntimeEntry`](/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md) |                                    `backgroundRuntime`                                   |
|              [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md)             |                                           `fcp`                                          |
|       [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md)       |                                        `actualFmp`                                       |
|               [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md)               | `updateTriggeredByBts`, `updateTriggeredByNative`, `updateGlobalProps`, `setNativeProps` |
|             [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md)            |                       `loadBundle`, `reloadBundle`, `reloadFromBts`                      |
|             [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md)            |                                       `lazyBundle`                                       |

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry`


---
url: /api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md
---

# InitBackgroundRuntimeEntry

<APISummary />

The `InitBackgroundRuntimeEntry` interface provides the key moments regarding the initialization of the [Background Thread Runtime](/guide/spec.md#background-thread-runtime). It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

In the initialization process, the metrics are defined as shown in the figure below:
![key moments of background thread runtime initialization](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/init-background-runtime-entry.png)

## Examples

This example demonstrates how to retrieve `InitBackgroundRuntimeEntry`。

**This is an example below:  performance-api**

**Entry:** `src/init-background-runtime-entry`
**Bundle:** `dist/init-background-runtime-entry.lynx.bundle`

```tsx {11-23}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { InitBackgroundRuntimeEntry, PerformanceEntry } from "@lynx-js/types";

import "./index.css";

export default function InitBackgroundRuntimeEntryExample(this: any) {
  const [initBackgroundRuntimeEntry, setInitBackgroundRuntimeEntry] = useState<string>("");

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      if (entry.entryType == "init" && entry.name == "backgroundRuntime") {
        // 3. Received "init.backgroundRuntime" event.
        const initBackgroundRuntimeEntry = entry as InitBackgroundRuntimeEntry;
        setInitBackgroundRuntimeEntry(JSON.stringify(initBackgroundRuntimeEntry, null, 4));
        observer.disconnect();
      }
    });
    // 2. register to listen to the "init.backgroundRuntime" event.
    observer.observe(["init.backgroundRuntime"]);
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello InitBackgroundRuntimeEntry~</text>
      <text className="entry">{initBackgroundRuntimeEntry}</text>
    </view>
  );
}

root.render(<InitBackgroundRuntimeEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```tsx
entryType: string;
```

Returns the entry type, which is always `init`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```tsx
name: string;
```

Returns the entry name, which is always `backgroundRuntime`.

### loadCoreStart

```tsx
loadCoreStart: number;
```

The start timestamp for initializing the [background thread runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### loadCoreEnd

```tsx
loadCoreEnd: number;
```

The end timestamp for initializing the [background thread runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.init-background-runtime-entry`


---
url: /api/lynx-api/performance-api/performance-entry/init-container-entry.md
---

# InitContainerEntry

<APISummary />

The `InitContainerEntry` interface documents key moments related for the [container](/guide/spec.md#container) preparation work before the Lynx page is displayed. It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

In the initialization process, the metrics are defined as shown in the figure below:
![key moments of container initialization](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/init-container-entry.png)

:::info
The key moments provided by this entry rely on the container through [`LynxView.setExtraTiming`](/api/lynx-native-api/lynx-view/set-extra-timing.md) provision.
:::

## Examples

This example demonstrates how to retrieve `InitContainerEntry`。

**This is an example below:  performance-api**

**Entry:** `src/init-container-entry`
**Bundle:** `dist/init-container-entry.lynx.bundle`

```tsx {10-22}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { InitContainerEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.css";

export default function InitContainerEntryExample(this: any) {
  const [initContainerEntry, setInitContainerEntry] = useState<string>("");

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      if (entry.entryType == "init" && entry.name == "container") {
        // 3. Received "init.container" event.
        const initContainerEntry = entry as InitContainerEntry;
        setInitContainerEntry(JSON.stringify(initContainerEntry, null, 4));
        observer.disconnect();
      }
    });
    // 2. register to listen to the "init.container" event.
    observer.observe(["init.container"]);
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello InitContainerEntry~</text>
      <text className="entry">{initContainerEntry}</text>
    </view>
  );
}

root.render(<InitContainerEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```tsx
entryType: string;
```

Returns the entry type, which is always `init`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```tsx
name: string;
```

Returns the entry name, which is always `container`.

### openTime

```tsx
openTime: number;
```

The time when the container starts loading a Lynx page。This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### containerInitStart

```tsx
containerInitStart: number;
```

The time when the container initialization starts. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### containerInitEnd

```tsx
containerInitEnd: number;
```

The time when the container initialization completes. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### prepareTemplateStart

```tsx
prepareTemplateStart: number;
```

The time when the container starts preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparing" means obtaining the TemplateBundle via network download, loading local cache, or any other method. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### prepareTemplateEnd

```tsx
prepareTemplateEnd: number;
```

The time when the container finishes preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparing" means obtaining the TemplateBundle via network download, loading local cache, or any other method. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.init-container-entry`


---
url: /api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md
---

# InitLynxviewEntry

<APISummary />

The `InitLynxviewEntry` interface provides key times regarding the initialization of [LynxView](/guide/spec.md#lynxview). It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

In the initialization process, the metrics are defined as shown in the figure below:
![key moments of lynxview initialization](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/init-lynxview-entry.png)

## Examples

This example demonstrates how to retrieve `InitLynxviewEntry`。

**This is an example below:  performance-api**

**Entry:** `src/init-lynx-view-entry`
**Bundle:** `dist/init-lynx-view-entry.lynx.bundle`

```tsx {10-21}
import { root, useMemo, useState } from "@lynx-js/react";
import type { InitLynxviewEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [initLynxviewEntry, setInitLynxviewEntry] = useState<string>("");

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "init" && entry.name == "lynxview") {
        // 3. Received "init.lynxview" event.
        const initLynxviewEntry = entry as InitLynxviewEntry;
        setInitLynxviewEntry(JSON.stringify(initLynxviewEntry, null, 4));
        observer.disconnect();
      }
    });
    // 2. register to listen to the "init.lynxview" event.
    observer.observe(["init.lynxview"]);
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello InitLynxviewEntry~</text>
      <text className="entry">{initLynxviewEntry}</text>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```tsx
entryType: string;
```

Returns the entry type, which is always `init`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```tsx
name: string;
```

Returns the entry name, which is always `lynxview`.

### createLynxStart

```tsx
createLynxStart: number;
```

The time LynxView starts creating. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### createLynxEnd

```tsx
createLynxEnd: number;
```

The time LynxView creation is complete. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.init-lynxview-entry`


---
url: /api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md
---

# LazyBundleEntry

<APISummary />

Through [lazy loading components](/react/code-splitting.md#lazy-loading-components), developers can render on demand, thereby improving user experience. `LazyBundleEntry` is used to record the performance data of lazy loading components and inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

## Example

This example demonstrates how to obtain a `LazyBundleEntry`.

**This is an example below:  performance-api**

**Entry:** `src/lazy-bundle-entry`
**Bundle:** `dist/lazy-bundle-entry.lynx.bundle`

```tsx {17-22,31-33}
import { lazy, root, Suspense, useState } from "@lynx-js/react";
import type { LazyBundleEntry, PerformanceEntry } from "@lynx-js/types";
import { useEffect } from "react";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

const MyLazyBundle = lazy(() => import("./MyLazyBundle.jsx"));

export default function LazyBundleEntryExample() {
  const [lazyBundleEntry, setLazyBundleEntry] = useState("");
  const [entryName, setEntryName] = useState("Waiting...");

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "resource") {
        // 3. Received "resource.lazyBundleEntry" event.
        const lazyBundleEntry = entry as LazyBundleEntry;
        setLazyBundleEntry(JSON.stringify(lazyBundleEntry, null, 4));
        setEntryName("LazyBundleEntry");
      }
    });
    // 2. Register to listen to the "resource" event.
    observer.observe(["resource"]);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello LazyBundleEntry~</text>
      <Suspense fallback={<text className="sub-text">Loading...</text>}>
        <MyLazyBundle />
      </Suspense>
      <ScrollItem title={entryName} value={lazyBundleEntry} />
    </view>
  );
}

root.render(<LazyBundleEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `resource`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The name of the performance event; the value for all instances of this class is fixed as `lazyBundle`.

### componentUrl

```tsx
componentUrl: string;
```

The URL string used to load the lazy loading component.

### size

```tsx
size: number;
```

The resource size of the lazy loading component, in bytes.

### mode

```tsx
mode: string;
```

The mode for loading the lazy loading component, with values: `preload` or `normal`.

### sync

```tsx
sync: boolean;
```

Whether the lazy loading component is rendered synchronously.

### loadSuccess

```tsx
loadSuccess: boolean;
```

Whether the lazy loading component was loaded successfully.

### requireStart

```tsx
requireStart: number;
```

The start timestamp for downloading the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

### requireEnd

```tsx
requireEnd: number;
```

The end timestamp for downloading the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

### decodeStart

```tsx
decodeStart: number;
```

The start timestamp for decoding the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

### decodeEnd

```tsx
decodeEnd: number;
```

The end timestamp for decoding the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.lazy-bundle-entry`


---
url: /api/lynx-api/performance-api/performance-entry/load-bundle-entry.md
---

# LoadBundleEntry

<APISummary />

_LoadBundle_ refers to the initial frame rendering pipeline triggered by [LynxView](/guide/spec.md#lynxview) loading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). `LoadBundleEntry` is used to record the performance data of this rendering pipeline and inherits from [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

The LoadBundle process flowchart is as follows:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/load-bundle-entry.png" />

:::tip

If you fail to receive `LoadBundleEntry`, it may be due to the following reasons:

**1. Rendering not triggered**

The rendering pipeline is not executed, typically because:

- **LynxView container state issues**: Width/Height is 0, not in the viewport, or not added to the window.
- **Business logic renders no content**: For example, in ReactLynx, the component's `render()` function returns `null` because data is not ready.

**2. Listener registered too late**

`LoadBundleEntry` is triggered only once upon completion of initial rendering. It is recommended to register the listener as early as possible:

- Register in `constructor` for class components.
- register in `useMemo` for functional components.

:::

## Example

This example demonstrates how to obtain a `LoadBundleEntry`.

**This is an example below:  performance-api**

**Entry:** `src/load-bundle-entry`
**Bundle:** `dist/load-bundle-entry.lynx.bundle`

```tsx {10-20}
import { root, useMemo, useState } from "@lynx-js/react";
import type { LoadBundleEntry, PerformanceEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function LoadBundleEntryExample(this: any) {
  const [loadBundleEntry, setLoadBundleEntry] = useState("");

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline" && entry.name == "loadBundle") {
        // 3. Received "pipeline.loadBundle" event.
        const loadBundleEntry = entry as LoadBundleEntry;
        setLoadBundleEntry(JSON.stringify(loadBundleEntry, null, 4));
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello LoadBundleEntry~</text>
      <ScrollItem title="LoadBundleEntry" value={loadBundleEntry} />
    </view>
  );
}

root.render(<LoadBundleEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `pipeline`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; the value for all instances of this class is fixed as `loadBundle`.

### identifier

```ts
identifier: string;
```

A marker for a particular rendering pipeline; the value for all instances of this class is fixed as an empty string.

### loadBundleStart

```ts
loadBundleStart: number;
```

The timestamp for the start of loading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadBundleEnd

```ts
loadBundleEnd: number;
```

The timestamp for the end of loading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### parseStart

```ts
parseStart: number;
```

The timestamp for the start of parsing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### parseEnd

```ts
parseEnd: number;
```

The timestamp for the end of parsing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadBackgroundStart

```ts
loadBackgroundStart: number;
```

The timestamp for the start of loading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadBackgroundEnd

```ts
loadBackgroundEnd: number;
```

The timestamp for the end of loading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineStart

```ts
pipelineStart: number;
```

The timestamp for the start of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineEnd

```ts
pipelineEnd: number;
```

The timestamp for the end of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderStart

```ts
mtsRenderStart: number;
```

The timestamp for the start of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderEnd

```ts
mtsRenderEnd: number;
```

The timestamp for the end of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveStart

```ts
resolveStart: number;
```

The timestamp for the start of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveEnd

```ts
resolveEnd: number;
```

The timestamp for the end of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutStart

```ts
layoutStart: number;
```

The timestamp for the start of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutEnd

```ts
layoutEnd: number;
```

The timestamp for the end of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteStart

```ts
paintingUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteEnd

```ts
paintingUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteStart

```ts
layoutUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteEnd

```ts
layoutUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintEnd

```ts
paintEnd: number;
```

The timestamp for the end of completing the final pixelation based on UI and UITree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### frameworkPipelineTiming

```ts
frameworkPipelineTiming: FrameworkPipelineTiming[keyof FrameworkPipelineTiming];
```

Performance data for key stages in [Framework Rendering](/guide/spec.md#framework-rendering). The type is [`FrameworkPipelineTiming`](/api/lynx-api/performance-api/framework-pipeline-timing.md).

### hostPlatformTiming

```ts
hostPlatformTiming: AndroidHostPlatformTiming |
  HarmonyHostPlatformTiming |
  IOSHostPlatformTiming;
```

Performance data for platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline), with type [`AndroidHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md) | [`HarmonyHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md) | [`IOSHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md).

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.load-bundle-entry`


---
url: /api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md
---

# MetricActualFmpEntry

<APISummary />

Actual FMP is a key performance metric that measures the time taken for the rendering of the "real data" of a page to complete. It reflects how quickly users see the actual data on the page. `MetricActualFmpEntry` interface provides timing information about this metric, inheriting from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

You can generate this metric by marking the [lynx pipeline](/guide/spec.md#lynx-pipeline) that contains important elements with [`__lynx_timing_flag="__lynx_timing_actual_fmp"`](/guide/performance/monitor-performance/timing-flag.md).

In the "real data" rendering, the timing for Actual FMP is as follows:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/performance-metrics-actual-fmp.png" />

Depending on different starting points, Lynx provides three metrics: `actualFmp`, `lynxActualFmp`, and `totalActualFmp`. Each metric's definition in the rendering process is illustrated in the diagram below:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/metric-actual-fmp-entry.png" />

## Example

This example demonstrates how to generate and obtain a `MetricActualFmpEntry`.

Lynx calculates the Actual Fmp when the marked elements have finished rendering. If you have provided container-related timestamps using [LynxView.setExtraTiming](/api/lynx-native-api/lynx-view/set-extra-timing.md), the `MetricActualFmpEntry` includes three metrics: `actualFmp`, `lynxActualFmp`, and `totalActualFmp`. Otherwise, the `MetricActualFmpEntry` only contains `lynxActualFmp`. After supplementing the [container](/guide/spec.md#container) timestamp, the remaining metrics will be recalculated. Once recalculation is complete, Lynx will send a new `lynxActualFmp` containing all the metrics.

**This is an example below:  performance-api**

**Entry:** `src/actual-fmp-entry`
**Bundle:** `dist/actual-fmp-entry.lynx.bundle`

```tsx {12-22,27,34}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { MetricActualFmpEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.scss";

export default function MetricActualFmpEntryExample(this: any) {
  const [msg, setMsg] = useState<string>("This is the initialization data.");
  const [actualfmpEntry, setActualFMPEntry] = useState<string>("");
  const [hasActualData, setHasActualData] = useState<boolean>(false);

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "metric" && entry.name == "actualFmp") {
        // 3. Received "metric.actualFmp" event.
        const actualfmpEntry = entry as MetricActualFmpEntry;
        setActualFMPEntry("actualfmpEntry : " + JSON.stringify(actualfmpEntry, null, 4));
      }
    });
    // 2. egister to listen to the "metric.actualFmp" event.
    observer.observe(["metric.actualFmp"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMsg("This is the actual data.");
      setHasActualData(true);
    }, 3000);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello MetricActualFmpEntry~</text>
      <text __lynx_timing_flag={hasActualData ? "__lynx_timing_actual_fmp" : ""}>{msg}</text>
      <text className="entry">{actualfmpEntry}</text>
    </view>
  );
}

root.render(<MetricActualFmpEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance Properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of performance event; the value for all instances of this class is fixed as `metric`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; the value for all instances of this class is fixed as `actualFmp`.

### actualFmp

```ts
actualFmp?: PerformanceMetric;
```

The time taken from preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of rendering for components and tags marked with `__lynx_timing_flag="__lynx_timing_actual_fmp"`, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `actualFmp = PipelineEntry.paintEnd - InitContainerEntry.prepareTemplateStart`.

### lynxActualFmp

```ts
lynxActualFmp: PerformanceMetric;
```

The time taken from loading the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of rendering for components and tags marked with `__lynx_timing_flag="__lynx_timing_actual_fmp"`, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `lynxActualFmp = PipelineEntry.paintEnd - LoadBundleEntry.loadBundleStart`.

### totalActualFmp

```ts
totalActualFmp?: PerformanceMetric;
```

The time taken from the user opening the page to the completion of rendering for components and tags marked with `__lynx_timing_flag="__lynx_timing_actual_fmp"`, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `totalActualFmp = PipelineEntry.paintEnd - InitContainerEntry.openTime`.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.metric-actual-fmp-entry`


---
url: /api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md
---

# MetricFcpEntry

<APISummary />

FCP is a key performance metric that measures the time taken for the [first-screen rendering](/guide/spec.md#first-screen-rendering-or-fsr) of lynx app to complete. It refers to the time taken for users to see any content (such as text or images) on a lynx app for the first time. `MetricFcpEntry` interface provides timing information about this metric, inheriting from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

The FCP event is triggered when Lynx completes the rendering of the first frame of the lynx app. For lynx apps that rely on network requests or asynchronous I/O to fetch data, the typical state monitored at FCP is the loading page or a placeholder, as shown in the diagram below:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/performance-metrics-fcp.png" />

Depending on different starting points, Lynx provides three metrics: `fcp`, `lynxFcp`, and `totalFcp`. Each metric's definition in the rendering process is illustrated in the diagram below:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/metric-fcp-entry.png" />

## Example

This example demonstrates how to obtain a `MetricFcpEntry`.

Lynx calculates the FCP upon completion of the first frame rendering. If you have provided container-related timestamps using [LynxView.setExtraTiming](/api/lynx-native-api/lynx-view/set-extra-timing.md), the `MetricFcpEntry` includes `fcp`, `lynxFcp`, and `totalFcp`. Otherwise, the `MetricFcpEntry` only contains `lynxFcp`. After supplementing the [container](/guide/spec.md#container) timestamp, the remaining metrics will be recalculated. Once recalculation is complete, Lynx will send a new `MetricFcpEntry` containing all the metrics.

**This is an example below:  performance-api**

**Entry:** `src/fcp-entry`
**Bundle:** `dist/fcp-entry.lynx.bundle`

```tsx {10-20}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { MetricFcpEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.scss";

export default function MetricFcpEntryExample(this: any) {
  const [fcpEntry, setFcpEntry] = useState<string>("");

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "metric" && entry.name == "fcp") {
        // 3. Received "metric.fcp" event.
        const fcpEntry = entry as MetricFcpEntry;
        setFcpEntry(JSON.stringify(fcpEntry, null, 4));
      }
    });
    // 2. Register to listen to the "metric.fcp" event.
    observer.observe(["metric.fcp"]);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello MetricFcpEntry~</text>
      <text className="entry">{fcpEntry}</text>
    </view>
  );
}

root.render(<MetricFcpEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance Properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of performance event; the value for all instances of this class is fixed as `metric`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; the value for all instances of this class is fixed as `fcp`.

### fcp

```ts
fcp?: PerformanceMetric;
```

The time taken from preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of the first rendering, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `fcp = LoadBundleEntry.paintEnd - InitContainerEntry.prepareTemplateStart`.

### lynxFcp

```ts
lynxFcp: PerformanceMetric;
```

The time taken from loading the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of the first rendering, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `lynxFcp = LoadBundleEntry.paintEnd - LoadBundleEntry.loadBundleStart`.

### totalFcp

```ts
totalFcp?: PerformanceMetric;
```

The time taken from the user opening the page to the completion of the first rendering, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `totalFcp = LoadBundleEntry.paintEnd - InitContainerEntry.openTime`.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.metric-fcp-entry`


---
url: /api/lynx-api/performance-api/performance-entry/pipeline-entry.md
---

# PipelineEntry

<APISummary />

`PipelineEntry` is responsible for recording performance data at key moments during the [Lynx Pipeline](/guide/spec.md#lynx-pipeline), specifically for [Framework Rendering](/guide/spec.md#framework-rendering) and [Pixel Pipeline](/guide/spec.md#pixel-pipeline). It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

The Lynx Pipeline refers to the complete process from the trigger of rendering to the final display. This process is divided into four main parts: Load, Parse, Framework Rendering (FrameworkPipeline), and Engine Rendering (PixelPipeline).

Due to the frequent triggering of the Lynx Pipeline, the framework only records the following two cases:

1. **Lynx Pipeline marked with [`__lynx_timing_flag`](/guide/performance/monitor-performance/timing-flag.md)**, which generate performance data as `PipelineEntry`.
2. **Lynx Pipeline triggered by loading and executing a [TemplateBundle](/api/lynx-native-api/template-bundle.md)**, which generate performance data as [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md).

The following is the flowchart for `PipelineEntry`:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/pipeline-entry.png" />

## Example

This example demonstrates how to generate and retrieve `PipelineEntry`.

**This is an example below:  performance-api**

**Entry:** `src/pipeline-entry`
**Bundle:** `dist/pipeline-entry.lynx.bundle`

```tsx {11-21,34}
import { root, useEffect, useState } from "@lynx-js/react";
import type { PerformanceEntry, PipelineEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function PipelineEntryExample() {
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [myName, setMyName] = useState<string | undefined>(undefined);

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline" event of "myPipeline".
        const pipelineEntry = entry as PipelineEntry;
        // `PerformanceEntry.identifier` is equal to `view.__lynx_timing_flag`.
        if (pipelineEntry.identifier == "myNamePipeline") {
          setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMyName("PipelineEntry");
    }, 2000);
  }, []);

  return (
    <view className="container">
      <text className="title" __lynx_timing_flag={myName ? "myNamePipeline" : ""}>Hello {myName}~</text>
      <ScrollItem title="PipelineEntry" value={pipelineEntry} />
    </view>
  );
}

root.render(<PipelineEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `pipeline`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; used to distinguish the source of the Pipeline trigger. Possible values include:

- `loadBundle`
- `reloadBundleFromNative`
- `reloadBundleFromBts`
- `updateTriggeredByBts`
- `updateTriggeredByNative`
- `updateGlobalProps`
- `setNativeProps`

### identifier

```ts
identifier: string;
```

A marker for a particular Lynx Pipeline. It can have the following two values:

1. For Lynx Pipelines marked with `__lynx_timing_flag`, **`identifier` equals the value of `__lynx_timing_flag`**.
2. For Lynx Pipelines triggered by loading and executing a `TemplateBundle`, **`identifier` is an empty string**.

### pipelineStart

```ts
pipelineStart: number;
```

The timestamp for the start of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineEnd

```ts
pipelineEnd: number;
```

The timestamp for the end of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderStart

```ts
mtsRenderStart: number;
```

The timestamp for the start of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderEnd

```ts
mtsRenderEnd: number;
```

The timestamp for the end of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveStart

```ts
resolveStart: number;
```

The timestamp for the start of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveEnd

```ts
resolveEnd: number;
```

The timestamp for the end of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutStart

```ts
layoutStart: number;
```

The timestamp for the start of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutEnd

```ts
layoutEnd: number;
```

The timestamp for the end of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteStart

```ts
paintingUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteEnd

```ts
paintingUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteStart

```ts
layoutUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteEnd

```ts
layoutUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintEnd

```ts
paintEnd: number;
```

The timestamp for the end of completing the final pixelation based on UI and UITree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### frameworkPipelineTiming

```ts
frameworkPipelineTiming: FrameworkPipelineTiming[keyof FrameworkPipelineTiming];
```

Performance data for key stages in [Framework Rendering](/guide/spec.md#framework-rendering). The type is [`FrameworkPipelineTiming`](/api/lynx-api/performance-api/framework-pipeline-timing.md).

### hostPlatformTiming

```ts
hostPlatformTiming: AndroidHostPlatformTiming |
  HarmonyHostPlatformTiming |
  IOSHostPlatformTiming;
```

Performance data for platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline), with type [`AndroidHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md) | [`HarmonyHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md) | [`IOSHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md).

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.pipeline-entry`


---
url: /api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md
---

# ReloadBundleEntry

<APISummary />

_ReloadBundle_ refers to the reload rendering pipeline triggered by the native interface `LynxView.reloadTemplate` or the frontend framework interface [`lynx.reload`](/api/lynx-api/lynx/lynx-reload.md), which causes the rendering pipeline of the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to be reloaded and executed. `ReloadBundleEntry` is used to record the performance data for the reload pipeline and inherits from [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

The reloadBundle process flowchart is as follows:

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/reload-bundle-entry-v9.png" />

## Example

This example demonstrates how to obtain a `ReloadBundleEntry`.

**This is an example below:  performance-api**

**Entry:** `src/reload-bundle-entry`
**Bundle:** `dist/reload-bundle-entry.lynx.bundle`

```tsx {14-25}
import { root, useCallback, useEffect, useState } from "@lynx-js/react";
import type { LoadBundleEntry, PerformanceEntry, PipelineEntry, ReloadBundleEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function ReloadBundleEntryExample() {
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [entryName, setEntryName] = useState("pending");

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline.loadBundle" event.
        const pipelineEntry = entry as PipelineEntry;
        setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
        if (entry.name.startsWith("reloadBundle")) {
          const reloadEntry = entry as ReloadBundleEntry;
          setEntryName(reloadEntry.name);
        } else if (entry.name.startsWith("loadBundle")) {
          const loadEntry = entry as LoadBundleEntry;
          setEntryName(loadEntry.name);
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    lynx.reload({}, () => {});
  }, []);

  return (
    <view className="container">
      <text className="title">Hello ReloadBundleEntry~</text>
      <text className="button" bindtap={onTap}>Click To Reload</text>
      <ScrollItem title={entryName} value={pipelineEntry} />
    </view>
  );
}

root.render(<ReloadBundleEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `pipeline`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific names of the performance events; the value for events triggered by the native interface `LynxView.reloadTemplate` is fixed as `reloadBundleFromNative`; the value for events triggered by the frontend framework interface `lynx.reload` is fixed as `reloadBundleFromBts`.

### identifier

```ts
identifier: string;
```

A marker for a particular rendering pipeline; the value for all instances of this class is fixed as an empty string.

### reloadBundleStart

```ts
reloadBundleStart: number;
```

The timestamp for the start of reloading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### reloadBundleEnd

```ts
reloadBundleEnd: number;
```

The timestamp for the end of reloading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### reloadBackgroundStart

```ts
reloadBackgroundStart: number;
```

The timestamp for the start of reloading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### reloadBackgroundEnd

```ts
reloadBackgroundEnd: number;
```

The timestamp for the end of reloading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineStart

```ts
pipelineStart: number;
```

The timestamp for the start of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineEnd

```ts
pipelineEnd: number;
```

The timestamp for the end of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderStart

```ts
mtsRenderStart: number;
```

The timestamp for the start of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderEnd

```ts
mtsRenderEnd: number;
```

The timestamp for the end of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveStart

```ts
resolveStart: number;
```

The timestamp for the start of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveEnd

```ts
resolveEnd: number;
```

The timestamp for the end of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutStart

```ts
layoutStart: number;
```

The timestamp for the start of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutEnd

```ts
layoutEnd: number;
```

The timestamp for the end of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteStart

```ts
paintingUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteEnd

```ts
paintingUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteStart

```ts
layoutUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteEnd

```ts
layoutUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintEnd

```ts
paintEnd: number;
```

The timestamp for the end of completing the final pixelation based on UI and UITree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### frameworkPipelineTiming

```ts
frameworkPipelineTiming: FrameworkPipelineTiming[keyof FrameworkPipelineTiming];
```

Performance data for key stages in [Framework Rendering](/guide/spec.md#framework-rendering). The type is [`FrameworkPipelineTiming`](/api/lynx-api/performance-api/framework-pipeline-timing.md).

### hostPlatformTiming

```ts
hostPlatformTiming: AndroidHostPlatformTiming |
  HarmonyHostPlatformTiming |
  IOSHostPlatformTiming;
```

Performance data for platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline), with type [`AndroidHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md) | [`HarmonyHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md) | [`IOSHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md).

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-entry.reload-bundle-entry`


---
url: /api/lynx-api/performance-api/performance-metric.md
---

# PerformanceMetric

<APISummary />

Describes the type that includes the performance metric name, metric value, and start/end timestamps.

In Lynx, several metric types are provided, such as [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md). Each metric type contains multiple metrics based on different starting points (for example, `MetricFcpEntry` includes metrics like `fcp`, `lynxFcp`, and `totalFcp`). To better describe the duration and timestamps of each metric, the `PerformanceMetric` type is designed.

## Attributes

### name

```ts
name: string;
```

The name of the metric, such as `fcp`, `lynxFcp`, `totalFcp`, etc.

### duration

```ts
duration: number;
```

The metric value in milliseconds with a microsecond precision(0.001ms). An example value is 100.099.

The calculation formula is: `duration = endTimestamp - startTimestamp`.

### startTimestampName

```ts
startTimestampName: string;
```

The name of the metric's start timestamp, such as `loadBundleStart` in [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md).

### startTimestamp

```ts
startTimestamp: number;
```

The start timestamp of the metric, an Unix timestamp in milliseconds with a microsecond precision(0.001ms). An example value is 1739594612307.429.

### endTimestampName

```ts
endTimestampName: string;
```

The name of the metric's end timestamp, such as `paintEnd` in [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md).

### endTimestamp

```ts
endTimestamp: number;
```

The end timestamp of the metric, an Unix timestamp in milliseconds with a microsecond precision(0.001ms). An example value is 1739594612307.429.

## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-metric`


---
url: /api/lynx-api/performance-api/performance-observer.md
---

# PerformanceObserver

<APISummary />

The `PerformanceObserver` is used to observe performance events and receive notifications when [Lynx Engine](/guide/spec.md#engine) generates [performance entries](/api/lynx-api/performance-api/performance-entry.md).
It must be created through [`lynx.performance.createObserver()`](/api/lynx-api/lynx/lynx-performance.md#createobserver) and bind with a callback function for handling received performance entries upon creation.

## Instance methods

[`PerformanceObserver.observe()`](/api/lynx-api/performance-api/performance-observer/observe.md)

Specify a set of performance entry types to observe and start observing.

[`PerformanceObserver.disconnect()`](/api/lynx-api/performance-api/performance-observer/disconnect.md)

Stop receiving performance entries.

## Examples

### Creating a PerformanceObserver

The following example creates a `PerformanceObserver` watching for [`metric.fcp`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`pipeline`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) entries.

**This is an example below:  performance-api**

**Entry:** `src/simple-observe`
```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function SimpleObserveExample(this: any) {
  const [receivedEntries, setReceivedEntries] = useState<Set<string>>(new Set<string>());

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fcp") {
        entryType = "MetricFcpEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["metric.fcp", "pipeline"]);
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver</text>
      </view>
      <view className="card">
        <text className="section-title">Received PerformanceEntry:</text>
        <view className="entries-container">
          {Array.from(receivedEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<SimpleObserveExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-observer`


---
url: /api/lynx-api/performance-api/performance-observer/disconnect.md
---

# PerformanceObserver: disconnect() method

<APISummary />

Stop receiving performance events.

## Syntax

```ts
disconnect();
```

### Parameters

None

### Return Value

None (`undefined`)

## Examples

The following example disconnects the `PerformanceObserver` to disable receiving any more performance events.

**This is an example below:  performance-api**

**Entry:** `src/performance-observer-disconnect`
**Bundle:** `dist/performance-observer-disconnect.lynx.bundle`

```tsx {17-18}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [hasReceivedEntries, setHasReceivedEntries] = useState<boolean>(false);

  function observePerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process performance entries
      setHasReceivedEntries(true);
      console.log(JSON.stringify(entry));
      // 4. stop receive more performance entries if needed
      observer.disconnect();
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["pipeline"]);
  }

  useMemo(() => {
    observePerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello PerformanceObserver::disconnect()</text>
      <view className="card">
        <text className="section-title">Is PerformanceObserver running?</text>
        <view className="entries-container">
          {hasReceivedEntries
            ? <text className="entry">Disconnect</text>
            : <text className="entry-item">Observing</text>}
        </view>
      </view>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-observer.disconnect`


---
url: /api/lynx-api/performance-api/performance-observer/observe.md
---

# PerformanceObserver: observe() method

<APISummary />

Specifies types of performance events to observe and starts observing. The callback function set when creating the `PerformanceObserver` will be invoked when a matching
[`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md) is received.

## Syntax

```ts
observe(entryIdentifiers: string[]): void
```

### Parameters

#### entryIdentifiers

```ts
entryIdentifiers: string[];
```

A string list of identifiers for the `PerformanceEntry` to be observed.

You can use **entryType** or **entryType.name** as identifiers. For example, you can use `"metric"` to listen to performance events for the entire metric type,
including [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md). Alternatively, you can use `"metric.fcp"` to listen only to the `MetricFcpEntry` performance event.

Refer to [`PerformanceEntry.entryType`](/api/lynx-api/performance-api/performance-entry.md#entryType) and [`PerformanceEntry.name`](/api/lynx-api/performance-api/performance-entry.md#name) for available types
and names. Unrecognized types will be ignored. If no valid types are found, `observe()` will not function.

:::tip
It is recommended to call this method during initialization, such as in the constructor of a root component or within the [`useMemo`](/api/react/Function.useMemo.md) Hook,
to ensure it is called as early as possible when the component or page loads, to avoid missing any data.
:::

### Return Value

None (`undefined`)

## Examples

### Observing all performance events under certain entryTypes

This example creates a `PerformanceObserver` that observes the entire `PerformanceEntry` of types through `["metric", "pipeline"]`.

**This is an example below:  performance-api**

**Entry:** `src/performance-observer-observe`
**Bundle:** `dist/performance-observer-observe.lynx.bundle`

```tsx {12-38}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [receivedTypeEntries, setReceivedTypeEntries] = useState<Set<string>>(new Set<string>());
  const [receivedSpecificEntries, setReceivedSpecificEntries] = useState<Set<string>>(new Set<string>());

  function observerAllEntryTypePerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric") {
        if (entry.name == "fcp") {
          entryType = "MetricFcpEntry";
        } else if (entry.name == "actualFmp") {
          entryType = "MetricActualFmpEntry";
        }
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedTypeEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric" and "pipeline" event.
    observer.observe(["metric", "pipeline"]);
  }

  function observeSpecificPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fcp") {
        entryType = "MetricFcpEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedSpecificEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["metric.fcp", "pipeline"]);
  }

  useMemo(() => {
    observerAllEntryTypePerformanceEntry();
    observeSpecificPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver::observe()</text>
      </view>
      <view className="card">
        <text className="section-title">Receive All EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedTypeEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
      <view className="card">
        <text className="section-title">Receive Specific EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedSpecificEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Observing specific performance events

This example creates a `PerformanceObserver` that observes `MetricFcpEntry` and the entire `PerformanceEntry` of type `pipeline` through `["metric.fcp", "pipeline"]`.

**This is an example below:  performance-api**

**Entry:** `src/performance-observer-observe`
**Bundle:** `dist/performance-observer-observe.lynx.bundle`

```tsx {42-61}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [receivedTypeEntries, setReceivedTypeEntries] = useState<Set<string>>(new Set<string>());
  const [receivedSpecificEntries, setReceivedSpecificEntries] = useState<Set<string>>(new Set<string>());

  function observerAllEntryTypePerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric") {
        if (entry.name == "fcp") {
          entryType = "MetricFcpEntry";
        } else if (entry.name == "actualFmp") {
          entryType = "MetricActualFmpEntry";
        }
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedTypeEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric" and "pipeline" event.
    observer.observe(["metric", "pipeline"]);
  }

  function observeSpecificPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fcp") {
        entryType = "MetricFcpEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedSpecificEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["metric.fcp", "pipeline"]);
  }

  useMemo(() => {
    observerAllEntryTypePerformanceEntry();
    observeSpecificPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver::observe()</text>
      </view>
      <view className="card">
        <text className="section-title">Receive All EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedTypeEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
      <view className="card">
        <text className="section-title">Receive Specific EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedSpecificEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Error:** No compatibility data found for `lynx-api.performance-api.performance-observer.observe`


---
url: /api/lynx-api/selector-query.md
---

# SelectorQuery

<APISummary />

Gets a reference to the specified node in order to call its methods or get its properties.

Depending on the method of creation, each `SelectorQuery` object will be assigned a root node. The scope of any node search will be limited to the leaf nodes of that node.

## Instance Methods

[`SelectorQuery.exec()`](/api/lynx-api/selector-query/selector-query-exec.md)

Execute all submitted UI node operation tasks.

[`SelectorQuery.select()`](/api/lynx-api/selector-query/selector-query-select.md)

Select the first node that matches the specified CSS selector under the root node specified by `SelectorQuery`.

[`SelectorQuery.selectAll()`](/api/lynx-api/selector-query/selector-query-select-all.md)

Select all nodes that match the specified CSS selector under the root node specified by `SelectorQuery`.

[`SelectorQuery.selectRoot()`](/api/lynx-api/selector-query/selector-query-select-root.md)

Select the root node specified by `SelectorQuery`.

[`SelectorQuery.selectUniqueID()`](/api/lynx-api/selector-query/selector-query-select-unique-id.md)

Select nodes by specifying `uid`.

## Example

Get the position and size of the specified `text` node:

```tsx
class Page extends Component {
  componentDidMount() {
    lynx
      .createSelectorQuery() // create SelectorQuery
      .select('#my-id') // Specify the selector of the target node
      .invoke({
        // Specify the operation for the target node
        method: 'boundingClientRect',
        success: function (res) {
          console.log(res);
        },
        fail: function (res) {
          console.log(res.code, res.data);
        },
      })
      .exec(); // Execute the query
  }

  render() {
    return (
      <view>
        <text id="my-id">...</text>
      </view>
    );
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.SelectorQuery`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Gets a reference to the specified node in order to call its methods or get its properties.




---
url: /api/lynx-api/selector-query/selector-query-exec.md
---

# SelectorQuery: exec() method

<APISummary />

Execute all submitted operations. Note that no node search and UI operations will actually be executed until `exec()` is called.

## Syntax

```ts
exec(): void;
```

### Parameters

None.

### Return Value

None (`undefined`).

## Example

Get the position and size of the specified `text` node:

```tsx
lynx
  .createSelectorQuery()
  .select('#my-id')
  .invoke({
    method: 'boundingClientRect',
    success: function (res) {
      console.log(res);
    },
    fail: function (res) {
      console.log(res.code, res.data);
    },
  })
  .exec();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.exec`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Execute all submitted operations.




---
url: /api/lynx-api/selector-query/selector-query-select-all.md
---

# SelectorQuery: selectAll() method

<APISummary />

Select all nodes that match the specified CSS selector under the root node specified by `SelectorQuery`.

## Syntax

```ts
selectAll(selector: string): NodesRef;
```

### Parameters

#### selector

CSS selector combination used for matching nodes. All nodes that match the specified selector combination will be returned.

The CSS selector used for matching nodes must be [CSS selectors supported by `select()`](/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

A `NodesRef` object instance representing this query result.

Please note that at this time, `SelectorQuery` will only save the query parameters provided by the user in the `NodesRef` object and will not execute the query immediately. Therefore, it is **NOT feasible** to view node information or determine whether the node can be found in the following way:

```js
let nodesRef = lynx.createSelectorQuery().selectAll('#the-id');
console.log(nodesRef); // always returning a valid NodesRef object
```

## Notices

### Do not use special characters other than numbers, letters, hyphens, and underscores in the id

Special characters may be parsed as part of a CSS selector or combinator.

For example, `selectAll('#m.x')` will be parsed as looking for elements with both `id=m` and `class=x` attributes, rather than looking for an element with `id` as `m.x`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.selectAll`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Select all nodes that match the specified CSS selector under the root node specified by `SelectorQuery`.




---
url: /api/lynx-api/selector-query/selector-query-select-root.md
---

# SelectorQuery: selectRoot() method

<APISummary />

Select the root node specified by `SelectorQuery`.

When using `lynx.createSelectorQuery()`, the selected element is the root element `<page>` of the entire page.

## Syntax

```ts
selectRoot(): NodesRef;
```

### Parameters

None.

### Return Value

A `NodesRef` object instance representing this query result.

## Examples

Set grayscale to the entire page:

```tsx
lynx
  .createSelectorQuery()
  .selectRoot()
  .setNativeProps({
    filter: 'grayscale(100%)',
  })
  .exec();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.selectRoot`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.4 | - |
| iOS | 2.4 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Select the root node specified by `SelectorQuery`.




---
url: /api/lynx-api/selector-query/selector-query-select-unique-id.md
---

# SelectorQuery: selectUniqueID() method

<APISummary />

Select nodes by specifying `uid`. It is usually used to select the corresponding node of the event target.

`uid` is a node's unique id. Each node has a dynamically assigned unique `uid`. `uid` can be obtained through the triggered event.

## Syntax

```ts
selectUniqueID(uniqueId: string | number): NodesRef;
```

### Parameters

#### uniqueId

The `uid` of the node to be selected.

### Return Value

A `NodesRef` object instance representing this query result.

## Examples

Add a background color to the target node of the tap event:

```tsx
const onTap = useCallback((event: ReactLynx.ITouchEvent) => {
  lynx
    .createSelectorQuery()
    .selectUniqueID(event.target.uid)
    .setNativeProps({
      'background-color': 'red',
    })
    .exec();
}, []);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.selectUniqueID`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Select nodes by specifying `uid`.




---
url: /api/lynx-api/selector-query/selector-query-select.md
---

# SelectorQuery: select() method

<APISummary />

Select the first node that matches the specified selector in the descendants of the root node specified in `SelectorQuery`.

## Syntax

```ts
select(selector: string): NodesRef;
```

### Parameters

#### selector

CSS selector combination used for matching nodes. The first node that matches the specified selector combination will be returned.

The CSS selector used for matching nodes must satisfy the following syntax:

##### Selectors

- Id selector `#`

```tsx
// '#my-id'
<view id="my-id" />
```

- Class selector `.`

```tsx
// '.class1'
<view className="class1" />
```

- Tag selector `tag`

```tsx
// 'view'
<view />
```

- Attribute selector (The `props` of a custom component do not belong to `attribute`, therefore the `attribute` selector cannot be used to match the `props` of a custom component.)
- `[attribute]`: Represents elements with an attribute name of attr.
- `[attribute=value]`: Represents elements with an attribute name of attr whose value is exactly value.
- `[attribute*=value]`: Represents elements with an attribute name of attr whose value contains at least one occurrence of value within the string.
- `[attribute^=value]`: Represents elements with an attribute name of attr whose value is prefixed (preceded) by value.
- `[attribute$=value]`: Represents elements with an attribute name of attr whose value is suffixed (followed) by value.

```tsx
// '[src]'
// '[src=xxx]'
// '[data-x]'
// '[data-x=xxx]'
<image src="xxx" data-x="xxx" />
```

- The free combination of the above selectors

```tsx
// 'image#my-id[src=xxx].class1.class2'
<image id="my-id" className="class1 class2" src="xxx" data-x="xxx" />
```

##### Combinators

- Child Element Combinator `>`

  - Search for the direct child nodes of the parent node.

```tsx
// '.the-parent > .the-child'
<view className="the-parent">
  <view className="the-child" />
</view>
```

- Descendant combinator ` ` (space)

  - Search for the descendant nodes of the parent node.

```tsx
// GOOD: '.the-ancestor   .the-descendant'
// BAD:  '.the-ancestor > .the-descendant'
<view className="the-ancestor">
  <view>
    <view className="the-descendant" />
  </view>
</view>
```

- The union of multiple selectors `,`

```tsx
#id1, #id2;
```

### Return Value

A `NodesRef` object instance representing this query result.

Please note that at this time, `SelectorQuery` will only save the query parameters provided by the user in the `NodesRef` object and will not execute the query immediately. Therefore, it is **NOT feasible** to view node information or determine whether the node can be found in the following way:

```js
let nodesRef = lynx.createSelectorQuery().select('#the-id');
console.log(nodesRef); // always returning a valid NodesRef object
```

## Notices

### Do not use special characters other than numbers, letters, hyphens, and underscores in the id

Special characters may be parsed as part of a CSS selector or combinator.

For example, `select('#m.x')` will be parsed as looking for elements with both `id=m` and `class=x` attributes, rather than looking for an element with `id` as `m.x`.

## Troubleshooting

Element manipulations are performed **asynchronously** after [`exec()`](/api/lynx-api/selector-query/selector-query-exec.md) is executed.
Therefore, it is not feasible to view element information or determine if an element can be found using the following methods:

```js
let nodesRef = lynx.createSelectorQuery().select('#the-id');
console.log(nodesRef); // always returning a valid NodesRef object
```

The correct approach is to examine the error information returned by the node operation functions invoked by the user.

### Common Error Code Definitions

```jsx
enum ErrorCode {
  SUCCESS = 0,
  UNKNOWN = 1,
  NODE_NOT_FOUND = 2,          // Node not found in the element tree
  METHOD_NOT_FOUND = 3,        // The specified method is not present on the found UI node
  PARAM_INVALID = 4,           // Invalid arguments as determined by the component implementer
  SELECTOR_NOT_SUPPORTED = 5,  // Usage of unsupported selectors
  NO_UI_FOR_NODE = 6,          // Node found in the element tree, but there is no corresponding UI
}
```

### Error Code 2 with the message "no node found for selector"

Common reasons include:

- An incorrect CSS selector was used;
- The node has not been rendered at the time of the node search.

#### Node Has Not Been Rendered at the Time of the Node Search

A common situation where a node cannot be found is when the node has not been rendered at the time the [`exec()`](/api/lynx-api/selector-query/selector-query-exec.md) function is called, such as when the node is within a conditional statement that is not satisfied.

For example, in the pseudocode below, during the initial render, since `show` is `false`, the `<view id="xxx" />` node will not be rendered. Therefore, attempting to obtain the node in `useEffect()` will fail.

```jsx
import { useEffect, useState } from '@lynx-js/react';

function App() {
  const [show, setShow] = useState(false);

  useEffect(() => {
    lynx
      .createSelectorQuery()
      .select('#xxx')
      .invoke({
        /** Args */
      })
      .exec();
  }, []);

  return show ? <view id="xxx" /> : null;
}
```

### Error Code 3

The specified node was found, but it does not have the corresponding UI method. Check:

- Whether the node indeed has the corresponding UI method.
- If the method name is spelled correctly.
- Whether there is another node with the same name, leading to the actual search finding a different node.

### Error Code 6

The target node exists in the element tree but lacks an actual UI node.
This issue usually occurs with `view` nodes because, for performance reasons, lynx may have optimized the node internally and not actually created it at the UI layer.
If you want to prevent this optimization, try adding an `id` to the target node.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.select`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** Select the first node that matches the specified selector in the descendants of the root node specified in `SelectorQuery`.




---
url: /api/lynx-native-api/lynx-background-runtime-client/on-evaluate-java-script-end.md
---

# onEvaluateJavaScriptEnd

<APISummary />

Called when background script evaluation finishes.

## Syntax

### Android

```java
public void onEvaluateJavaScriptEnd(String url);
```

### iOS

```objc
- (void)runtime:(LynxBackgroundRuntime *)runtime didEvaluateJavaScriptEnd:(NSString *)url;
```

### Harmony

```ts
public onEvaluateJavaScriptEnd(url: string): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime-client.on-evaluate-java-script-end`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when background script evaluation finished.




---
url: /api/lynx-native-api/lynx-background-runtime-client/on-module-method-invoked.md
---

# onModuleMethodInvoked

<APISummary />

Called when a module method invocation is completed in the background runtime.

## Syntax

### Android

```java
public void onModuleMethodInvoked(String module, String method, int error_code);
```

#### Parameters

- `module`: Module name.
- `method`: Method name.
- `error_code`: Error code if the invocation failed.

### Harmony

```ts
public onModuleMethodInvoked(module: string, method: string, error_code: number): void;
```

#### Parameters

- `module`: Module name.
- `method`: Method name.
- `error_code`: Error code if the invocation failed.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime-client.on-module-method-invoked`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when a module method invocation completed in background runtime.




---
url: /api/lynx-native-api/lynx-background-runtime-client/on-received-error.md
---

# onReceivedError

<APISummary />

Called when an error is received in the background runtime. The error may originate from JS or native code.

## Syntax

### Android

```java
public void onReceivedError(LynxError error);
```

#### Parameters

- `error`: Error information.

### iOS

```objc
- (void)runtime:(LynxBackgroundRuntime *)runtime didReceiveError:(NSError *)error;
```

#### Parameters

- `error`: Error information.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime-client.on-received-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when an error is received in background runtime.




---
url: /api/lynx-native-api/lynx-background-runtime.md
---

# LynxBackgroundRuntime

LynxBackgroundRuntime is Lynx's off-main-thread runtime. It executes script logic that does not directly affect screen pixel rendering, such as business data processing, networking, and Native Module calls. It sits at the same level as `LynxView`: `LynxView` renders UI, while `LynxBackgroundRuntime` runs non-rendering scripts.

## What It’s For

- Runs business logic that doesn’t render pixels
- Handles networking and Native Module calls off the UI thread
- Complements `LynxView` without interfering with rendering

## Core APIs

- [Evaluate Script](/api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md#L1-1)
- [Evaluate Bundle Script](/api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md#L1-1)
- [Send Global Event](/api/lynx-native-api/lynx-background-runtime/send-global-event.md#L1-1)
- [Add Lifecycle Client](/api/lynx-native-api/lynx-background-runtime/add-lynx-background-runtime-client.md#L1-1) / [Remove Lifecycle Client](/api/lynx-native-api/lynx-background-runtime/remove-lynx-background-runtime-client.md#L1-1)
- [Destroy](/api/lynx-native-api/lynx-background-runtime/destroy.md#L1-1)
- [Call JS Function](/api/lynx-native-api/lynx-background-runtime/call-js-function.md#L1-1)



---
url: /api/lynx-native-api/lynx-background-runtime/add-lynx-background-runtime-client.md
---

# addLynxBackgroundRuntimeClient

<APISummary />

Register lifecycle event listeners for `LynxBackgroundRuntime`.

## Syntax

### Android

```java
public void addLynxBackgroundRuntimeClient(LynxBackgroundRuntimeClient client);
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### iOS

```objc
- (void)addLifecycleClient:(nonnull id<LynxBackgroundRuntimeLifecycle>)lifecycleClient;
```

#### Parameters

- `lifecycleClient`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### Harmony

```ts
public addLifecycleClient(client: LynxBackgroundRuntimeClient): void;
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.add-lynx-background-runtime-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** register lifecycle observer for background runtime




---
url: /api/lynx-native-api/lynx-background-runtime/call-js-function.md
---

# callJSFunction

<APISummary />

Invoke a JavaScript function from `LynxBackgroundRuntime`.

## Syntax

### Android

```java
public void callFunction(String module, String method, JavaOnlyArray arguments);
```

#### Parameters

- `module`: Target JS module name.
- `method`: Method name in the module.
- `arguments`: Arguments array for the function.

### iOS

```objc
- (void)callFunction:(nonnull NSString *)moduleName
          withMethod:(nonnull NSString *)methodName
          withParams:(nullable NSArray *)params;
```

#### Parameters

- `moduleName`: Target JS module name.
- `methodName`: Method name in the module.
- `params`: Parameters array for the function.

### Harmony

```ts
callJSFunction(module: string, method: string, params: Object[]): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.call-js-function`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** invoke js function from background runtime




---
url: /api/lynx-native-api/lynx-background-runtime/destroy.md
---

# destroy

<APISummary />

Destroy `LynxBackgroundRuntime` and release all resources related to the runtime.

## Syntax

### Android

```java
public void destroy();
```

### iOS

rely on garbage collect.

### Harmony

rely on garbage collect.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** manually destroy background runtime instance




---
url: /api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md
---

# evaluateJavaScript

<APISummary />

Run background script logic.

## Syntax

### Android

```java
public void evaluateJavaScript(String url, @NonNull String sources);
public void evaluateTemplateBundle(String url, @NonNull TemplateBundle bundle, @NonNull String js_file);
```

#### Parameters

- `url`: Unique identifier for the script.
- `sources`: Script content.
- `bundle`: Pre-parsed `TemplateBundle` containing the script.
- `js_file`: Related JS file name inside the bundle.

### iOS

```objc
- (void)evaluateJavaScript:(NSString *)url withSources:(NSString *)sources;
- (void)evaluateTemplateBundle:(NSString *)url
                   widthBundle:(LynxTemplateBundle *)bundle
                    withJSFile:(NSString *)jsFile;
```

#### Parameters

- `url`: Unique identifier for the script.
- `sources`: Script content.
- `bundle`: Pre-parsed `LynxTemplateBundle` containing the script.
- `jsFile`: Related JS file name inside the bundle.

### Harmony

```ts
evaluateJavaScript(url: string, sources: string): void;
evaluateBundleScript(url: string, bundle: TemplateBundle, jsFileName: string): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.evaluate-java-script`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** evaluate background runtime script




---
url: /api/lynx-native-api/lynx-background-runtime/remove-lynx-background-runtime-client.md
---

# removeLynxBackgroundRuntimeClient

<APISummary />

Remove lifecycle event listeners from `LynxBackgroundRuntime` (counterpart of `addLynxBackgroundRuntimeClient`).

## Syntax

### Android

```java
public void removeLynxBackgroundRuntimeClient(LynxBackgroundRuntimeClient client);
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### iOS

```objc
- (void)removeLifecycleClient:(nonnull id<LynxBackgroundRuntimeLifecycle>)lifecycleClient;
```

#### Parameters

- `lifecycleClient`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### Harmony

```ts
public removeLifecycleClient(client: LynxBackgroundRuntimeClient): void;
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.remove-lynx-background-runtime-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** remove lifecycle observer for background runtime




---
url: /api/lynx-native-api/lynx-background-runtime/send-global-event.md
---

# sendGlobalEvent

<APISummary />

Send a global event from `LynxBackgroundRuntime` to the frontend. The frontend can listen via `GlobalEventEmitter`.

## Syntax

### Android

```java
public void sendGlobalEvent(String name, JavaOnlyArray params);
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by the event.

### iOS

```objc
- (void)sendGlobalEvent:(nonnull NSString *)name withParams:(nullable NSArray *)params;
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by the event.

### Harmony

```ts
runtime.sendGlobalEvent('eventName', []);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.send-global-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** send global event to js enviroment from background runtime




---
url: /api/lynx-native-api/lynx-context/send-global-event.md
---

# sendGlobalEvent

<APISummary />

Send global events to the front end through the client, and the front end can listen to the event through `GlobalEventEmitter`.

## Syntax

### Harmony

```typescript
sendGlobalEvent(name: string, params: Object[]): void;
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by global events.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.send-global-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** send global event to js enviroment




---
url: /api/lynx-native-api/lynx-context/set-extra-timing.md
---

# setExtraTiming

<APISummary />

This interface is used to supplement key performance data before loading the Lynx page, specifically including the following items from [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md):

- Page open time (`openTime`)
- Timestamp for the start of preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) (`prepareTemplateStart`)
- Timestamp for the end of preparing the TemplateBundle (`prepareTemplateEnd`)
- Timestamp for the start of [container](/guide/spec.md#container) initialization (`containerInitStart`)
- Timestamp for the end of container initialization (`containerInitEnd`)

Upon successfully updating all timestamps using this interface, the `InitContainerEntry` performance event will be triggered. Depending on the timing of the configuration, it may also trigger the calculation of `fcp`, `totalFcp`, `actualFmp`, and `totalActualFmp` metrics, along with dispatching new performance events for [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).

:::caution
Timestamps within extraTiming cannot be overwritten, meaning that multiple calls to this interface attempting to repeatedly update a timestamp will yield no effect.
:::

## Syntax

### Harmony

```typescript
public setExtraTiming(extraTiming: LynxExtraTiming): void;
```

#### Parameters

- `extraTiming`: Used to supplement key performance data before loading the Lynx page.

The specific definition of `LynxExtraTiming` is as follows:

```typescript
export class LynxExtraTiming {
  public static readonly OPEN_TIME = 'openTime';
  public static readonly CONTAINER_INIT_START = 'containerInitStart';
  public static readonly CONTAINER_INIT_END = 'containerInitEnd';
  public static readonly PREPARE_TEMPLATE_START = 'prepareTemplateStart';
  public static readonly PREPARE_TEMPLATE_END = 'prepareTemplateEnd';

  public openTime: number = 0;
  public containerInitStart: number = 0;
  public containerInitEnd: number = 0;
  public prepareTemplateStart: number = 0;
  public prepareTemplateEnd: number = 0;
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.set-extra-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** set extra timing from outside.




---
url: /api/lynx-native-api/lynx-context/update-font-scale.md
---

# updateFontScale

<APISummary />

Changing the font scaling ratio in client settings will automatically change the text size.

## Syntax

### Harmony

```typescript
updateFontScale(scale: number): void;
```

#### Parameters

- `scale`: Font scaling.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.update-font-scale`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** update font scale of lynxView




---
url: /api/lynx-native-api/lynx-context/update-meta-data.md
---

# updateMetaData

<APISummary />

Using [LynxUpdateMeta](/api/lynx-native-api/lynx-update-meta.md) to update `LynxView`, it is the main entrance for the client to update template data.

## Syntax

### Harmony

```typescript
updateMetaData(data: MetaData): void;
```

#### Parameters

- `data`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.update-meta-data`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** update lynx page by new data.




---
url: /api/lynx-native-api/lynx-context/update-viewport.md
---

# updateViewport

<APISummary />

The client updates the `LynxView` view size.

## Syntax

### Harmony

```typescript
public updateViewport(width: number, widthMode: number, height: number, heightMode: number): void;
```

#### Parameters

- `width`: Current `LynxView` width.
- `widthMode`: The measure mode for width. 0: Indefinite, 1: Definite, 2: AtMost.
- `height`: Current `LynxView` height.
- `heightMode`: The measure mode for height. 0: Indefinite, 1: Definite, 2: AtMost.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.update-viewport`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** update viewport of lynxView




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/cancel.md
---

# cancel

<APISummary />

Cancel the request of the requiring resource.

## Syntax

### Android

```java
public void cancel(LynxResourceRequest request);
```

#### Parameters

- `request`: the requiring request.

:::note

- This method is optional to be implemented.

:::

### Harmony

```typescript
abstract cancel(request: LynxResourceRequest): void;
```

#### Parameters

- `request`: Request to be canceled.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.cancel`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Cancel the request of the requiring resource.




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource-path.md
---

# fetchResourcePath

<APISummary />

`LynxEngine` internally calls this method to obtain the path of the common resource on the local disk, and the return result is required to be of `String` type.

## Syntax

### Android

```java
public abstract void fetchResourcePath(
    LynxResourceRequest request, LynxResourceCallback<String> callback);
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Path on the disk of the requiring resource.

:::note

- This method must be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchResourcePath:(nonnull LynxResourceRequest *)request
                           onComplete:(LynxGenericResourcePathCompletionBlock _Nonnull)callback;
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Path on the disk of the requiring resource.

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract fetchResourcePath(request: LynxResourceRequest, callback: AsyncCallback<string>): void;
```

#### Parameters

- `request`: Request to obtain the path of the common resource on the local disk.
- `callback`: with path on the disk of the requiring resource.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.fetch-resource-path`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxEngine internally calls this method to obtain the path of the common resource on the local disk, and the return result is required to be of String type.




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource.md
---

# fetchResource

<APISummary />

`LynxEngine` internally calls this method to obtain the general resource content, and the return result is required to be the resource content `byte[]` type.

## Syntax

### Android

```java
public abstract void fetchResource(
    LynxResourceRequest request, LynxResourceCallback<byte[]> callback);
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Contents of the requiring resource.

:::note

- This method must be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchResource:(nonnull LynxResourceRequest *)request
                       onComplete:(LynxGenericResourceCompletionBlock _Nonnull)callback;
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Contents of the requiring resource.

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract fetchResource(request: LynxResourceRequest, callback: AsyncCallback<ArrayBuffer>): void;
```

#### Parameters

- `request`: Request to obtain the general resource content.
- `callback`: Containing contents of the requiring resource.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.fetch-resource`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxEngine internally calls this method to obtain the general resource content, and the return result is required to be the resource content byte[] type.




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/fetch-stream.md
---

# fetchStream

<APISummary />

`LynxEngine` internally calls this method to obtain resource content in a streaming manner.

## Syntax

### Android

```java
public void fetchStream(LynxResourceRequest request, StreamDelegate delegate);
```

#### Parameters

- `request`: Request for the requiring resource.
- `delegate`: Streaming of the requiring resource.

:::note

- This method is optional to be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchStream:(nonnull LynxResourceRequest *)request
                     withStream:(nonnull id<LynxResourceStreamLoadDelegate>)delegate;
```

#### Parameters

- `request`: Request for the requiring resource.
- `delegate`: Streaming of the requiring resource.

:::note

- This method is optional to be implemented.

:::

### Harmony

```typescript
fetchStream(request: LynxResourceRequest, delegate: LynxStreamDelegate): void;
```

#### Parameters

- `request`: Request to obtain resource content in a streaming manner.
- `delegate`: streaming of the requiring resource.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.fetch-stream`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxEngine internally calls this method to obtain resource content in a streaming manner.




---
url: /api/lynx-native-api/lynx-load-meta.md
---

# LynxLoadMeta

<APISummary />

`LynxLoadMeta` is the metadata structure used by `LynxView` to load templates. It will be used as the input parameter of [loadTemplate](/api/lynx-native-api/lynx-view/load-template.md). Users can use `LynxLoadMeta` to specify many parameters of loading templates, such as specifying template content, template initial data, and other additional configuration information;

## Android:

### Field

- `url: String `: Template file path;
- `binaryData: byte[]`: The binary file data of the template;
- `bundle: TemplateBundle`: [TemplateBundle](/api/lynx-native-api/template-bundle.md) object parsed in advance by the template's binary file data;
- `initialData: TemplateData`: Initial data specified by the client during the first screen loading process;
- `globalProps: TemplateData`: Global properties, which will be synchronized to the template after the template is loaded.
- `loadMode: LynxLoadMode`: Loading mode, the default value is `LynxLoadMode.NORMAL`.
- `loadOptions: EnumSet<LynxLoadOption>`: Additional configuration information when loading templates;
- `lynxViewConfig: Map<String, String>`: Page Config information passed in when loading the template.

:::info

url, binaryData, bundle are the required parameters for template loading. You can pass only one or all of them. The priority relationship is as follows:
bundle > binaryData > url

:::

:::info

loadOptions is additional configuration information when loading a template. Currently the following configuration items are supported:

- **RECYCLE\_TEMPLATE\_BUNDLE**: After LynxView uses url or binaryData to load the template, it supports returning a TemplateBundle to the calling business party through LynxViewClient;
- **DUMP\_ELEMENT**: When LynxView loads a Bundle, copy the ElementBundle to the TemplateBundle and pass it back through the LynxViewClient;

:::

:::info

loadMode is the loading mode of the template. Currently, the following configuration items are supported:

- **NORMAL**: Default loading mode.
- **PRE\_PAINTING**: Suspend JS events when loading the template. Events will be sent during update, and layout will be blocked until the update is complete.
- **PRE\_PAINTING\_DRAW**: Suspend JS events when loading the template. Events will be sent during update.

:::

### Construction

To construct a `LynxLoadMeta` object on the `Android` platform, you need to use `LynxLoadMeta.Builder`:

```java
LynxLoadMeta.Builder builder = new LynxLoadMeta.Builder();
builder.setUrl();
builder.setBinaryData();
builder.setTemplateBundle();
builder.setInitialData();
builder.setGlobalProps();
builder.setLoadMode();
builder.addLoadOption();
builder.setLynxViewConfig();
LynxLoadMeta meta = builder.build();
```

## iOS

### Field

- `url: NSString*`: Template file path;
- `binaryData: NSData*`: The binary file data of the template;
- `templateBundle: LynxTemplateBundle*`: [TemplateBundle](/api/lynx-native-api/template-bundle.md) object parsed in advance by the template's binary file data;
- `initialData: LynxTemplateData*`: Initial data specified by the client during the first screen loading process;
- `globalProps: LynxTemplateData*`: Global properties, which will be synchronized to the template after the template is loaded.
- `loadMode: LynxLoadMode`: Loading mode, the default value is `LynxLoadModeNormal`.
- `loadOption: LynxLoadOption`: Additional configuration information when loading templates;
- `lynxViewConfig: NSMutableDictionary<NSString*, id>*`: Page Config information passed in when loading the template.

:::info

url, binaryData, templateBundle are the required parameters for template loading. You can pass only one or all of them. The priority relationship is as follows:
templateBundle > binaryData > url

:::

:::info

loadOption is additional configuration information when loading a template. Currently the following configuration items are supported:

- **RECYCLE\_TEMPLATE\_BUNDLE**: After LynxView uses url or binaryData to load the template, it supports returning a TemplateBundle to the calling business party through LynxViewClient;
- **DUMP\_ELEMENT**: When LynxView loads a Bundle , copy the ElementBundle to the TemplateBundle and pass it back through the LynxViewClient;

:::

:::info

loadMode is the loading mode of the template. Currently, the following configuration items are supported:

- **LynxLoadModeNormal**: Default loading mode.
- **LynxLoadModePrePainting**: Suspend JS events when loading the template. Events will be sent during update, and layout will be blocked until the update is complete.

:::

### Construction

On the iOS platform, you can construct a LynxLoadMeta object as follows:

```objective-c
LynxLoadMeta* meta = [LynxLoadMeta init];
meta.url = @"";
meta.binaryData = nil;
meta.templateBundle = nil;
meta.initialData = nil;
meta.globalProps = nil;
meta.loadMode = LynxLoadModeNormal;
meta.loadOption = LynxLoadOptionDumpElement | LynxLoadOptionRecycleTemplateBundle;
meta.lynxViewConfig = nil;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-load-meta`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |

**Description:** MetaData of LynxEngine loadProcess




---
url: /api/lynx-native-api/lynx-media-resource-fetcher/fetch-image.md
---

# fetchImage

<APISummary />

`LynxEngine` will use this method to obtain the bitmap information of the image, and the return content must be of `Closeable` type.

## Syntax

### Android

```java
public void fetchImage(LynxResourceRequest request, LynxResourceCallback<Closeable> callback);
```

#### Parameters

- `request`: Request for the resource.
- `callback`: Response with the needed drawable.

:::note

- This method is optional to be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchUIImage:(LynxResourceRequest *_Nonnull)request
                      onComplete:(LynxMediaResourceCompletionBlock _Nonnull)response;
```

#### Parameters

- `request`: Request for the resource.
- `response`: Response with the needed drawable.

:::note

- This method is optional to be implemented.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-media-resource-fetcher.fetch-image`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxEngine will use this method to obtain the bitmap information of the image, and the return content must be of Closeable type.




---
url: /api/lynx-native-api/lynx-media-resource-fetcher/is-local-resource.md
---

# isLocalResource

<APISummary />

`LynxEngine` internally calls this method to determine whether the resource path exists on disk.

## Syntax

### Android

```java
public OptionalBool isLocalResource(String url);
```

#### Parameters

- `url`: Input path.

#### Return

- TRUE if is a local path, FALSE if not a local path and UNDEFINED if not sure.

:::note

- This method is optional to be implemented.

:::

### iOS

```objc
- (LynxResourceOptionalBool)isLocalResource:(NSURL *_Nonnull)url;
```

#### Parameters

- `url`: Input path.

#### Return

- TRUE if is a local path, FALSE if not a local path and UNDEFINED if not sure.

:::note

- This method is optional to be implemented.

:::

### Harmony

```typescript
isLocalResource(url: string): LynxOptionalBool;
```

#### Parameters

- `url`: Input path.

#### Return

- TRUE if is a local path, FALSE if not a local path, UNDEFINED if not sure.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-media-resource-fetcher.is-local-resource`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxEngine internally calls this method to determine whether the resource path exists on disk.




---
url: /api/lynx-native-api/lynx-media-resource-fetcher/should-redirect-url.md
---

# shouldRedirectUrl

<APISummary />

`LynxEngine` redirects the image path by calling this method internally, and the return result is required to be of `String` type

## Syntax

### Android

```java
public abstract String shouldRedirectUrl(LynxResourceRequest request);
```

#### Parameters

- `request`: Request for the resource.
- `callback`: The target url.

:::note

- This method must be implemented.

:::

### iOS

```objc
- (NSString *_Nonnull)shouldRedirectUrl:(LynxResourceRequest *_Nonnull)request;
```

#### Parameters

- `request`: Request for the resource.
- `callback`: The target url.

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract shouldRedirectUrl(request: LynxResourceRequest): string;
```

#### Parameters

- `request`: Request to be redirected.

#### Return

- The target url.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-media-resource-fetcher.should-redirect-url`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxEngine redirects the image path by calling this method internally, and the return result is required to be of String type.




---
url: /api/lynx-native-api/lynx-service.md
---

# LynxService API

<APISummary />


## Introduction

Lynx Service provides Lynx Engine with host-specific capabilities, including image, log, and [FetchAPI](/guide/interaction/networking.md#fetch-api) capabilities.
Different hosts have specific requirements for their own image, log, and network libraries, so Lynx Engine opens up autonomous access capabilities for such scenarios through the LynxService API.

## Overall Design

Lynx Engine and Lynx Service adopt a dependency-separation design. In terms of the dependency relationship, Lynx Service depends on the LynxService API provided by Lynx Engine to implement itself, while Lynx Engine does not depend on LynxService. At runtime, Lynx Engine will search for the registered Lynx Service through the service lookup mechanism and call it via the LynxService API.

## LynxService API

The LynxService API is provided by Lynx Engine and is designed to specify the capabilities of LynxService. Lynx Service needs to correctly implement itself in accordance with the requirements of the LynxService API to ensure that Lynx Engine can properly use this basic capability.

## 1. Quick Access

Lynx provides a default implementation of Lynx Service, which can be directly [accessed](/guide/start/integrate-with-existing-apps.md)

## 2. Lynx Service Customization

If there are custom requirements, you can also quickly implement and register relevant content according to your own needs. The following will take log service as an example to introduce how to implement and register a custom Lynx Service:

<Steps>
  ### Interface Implementation

  <Tabs groupId="lynx-service-api">
    <Tab label="iOS">
      - 1. Implement `LynxServiceLogProtocol`

      ```objective-c title="YourLogService.h"
      #import <Lynx/LynxService.h>
      #import <Lynx/LynxServiceLogProtocol.h>

      // Implement LynxServiceLogProtocol
      @interface YourLogService : NSObject <LynxServiceLogProtocol>
      @end
      ```

      - 2. Use the `LynxServiceRegister` to achieve automatic registration.
      - 3. Implement `serviceBizID` and `serviceScope`. These two methods have no practical significance and will be removed later.
      - 4. Implement `serviceType`. It is required to return the type implemented by this Service. See LynxService.h for details.
      - 5. (Recommended) Implement `sharedInstance` to make it a singleton class. Based on the current Lynx Service design, only one instance of a certain type of Service will be used globally. It is recommended to implement it as a singleton class.
      - 6. Implement all the interfaces required by `LynxServiceLogProtocol`.

      <CodeFold toggle>
        ```objective-c title="YourLogService.mm"
        #import "YourLogService.h"

        [[maybe_unused]] void logWrite(unsigned int level, const char *tag, const char *format) {
          if (format == NULL) {
            return;
          }
          NSLog(@"[%s] %s", tag == NULL ? "" : tag, format);
        }

        // Use the LynxServiceRegister macro to achieve automatic registration
        @LynxServiceRegister(LynxLogService);

        // Implement LynxLogService
        @implementation LynxLogService

        // Irrelevant property, will be removed later
        + (NSString*)serviceBizID {
          return DEFAULT_LYNX_SERVICE;
        }

        // Irrelevant property, will be removed later
        + (LynxServiceScope)serviceScope {
          return LynxServiceScopeDefault;
        }

        // Return the corresponding service type for runtime lookup
        + (NSUInteger)serviceType {
          return kLynxServiceLog;
        }

        // Recommended: Implement as a singleton
        + (instancetype)sharedInstance {
          static dispatch_once_t onceToken;
          static YourLogService *logService;
          dispatch_once(&onceToken, ^{
            logService = [[YourLogService alloc] init];
          });
          return logService;
        }

        // Implement all the interfaces required by LynxServiceLogProtocol
        - (void *)getWriteFunction {
          return (void *)logWrite;
        }

        @end
        ```
      </CodeFold>
    </Tab>

    <Tab label="Android">
      Implement `ILynxLogService`:

      <CodeFold toggle>
        ```kotlin title="YourLogService.kt"
        object YourLogService : ILynxLogService {
          private var logOutputChannel: LogOutputChannelType = LogOutputChannelType.Platform

          override fun logByPlatform(
            level: Int,
            tag: String,
            msg: String,
          ) {
            // Implemention
          }

          override fun isLogOutputByPlatform(): Boolean = logOutputChannel == LogOutputChannelType.Platform

          override fun getDefaultWriteFunction(): Long = 0

          override fun switchLogToSystem(enableSystemLog: Boolean) {}

          override fun getLogToSystemStatus(): Boolean = false
        }
        ```
      </CodeFold>
    </Tab>

    <Tab label="Harmony">
      Implement `ILynxLogService`:

      <CodeFold toggle>
        ```typescript title="YourLogService.ets"
        import { ILynxLogService } from '@lynx/lynx';

        export class YourLogService implements ILynxLogService {
          static instance = new YourLogService();

          logByPlatform(level: number, tag: string, message: string): void {
            console.log(`level: ${level} tag: ${tag} message: ${message}`);
          }

          isLogOutputByPlatform(): boolean {
            return true;
          }

          getDefaultWriteFunction(): number {
            return 0;
          }
        }
        ```
      </CodeFold>
    </Tab>
  </Tabs>

  <div style={{ height: 30}} />

  ### Service Register

  <Tabs groupId="lynx-service-api">
    <Tab label="iOS">
      Lynx Service has an automatic registration mechanism in iOS. In the implementation stage, the `LynxServiceRegister` macro has been used to complete the quick automatic registration.

      If you use your own implementation of Lynx Service, please delete the [default implementation](/guide/start/integrate-with-existing-apps.md#platform=ios) provided by Lynx.

      ```diff title="Podfile"
      pod 'LynxService', '3.6.0', :subspecs => [
            'Image',
      -     'Log',
            'Http',
        ]
      ```
    </Tab>

    <Tab label="Android">
      Replace the implementation of log service in `LynxServiceCenter` in the [integration documentation](/guide/start/integrate-with-existing-apps.md#platform=android) with your implementation.

      ```diff
      - LynxServiceCenter.inst().registerService(ILynxLogService::class.java, LynxLogService)
      + LynxServiceCenter.inst().registerService(ILynxLogService::class.java, YourLogService)
      ```

      And delete related dependencies

      ```diff title="build.gradle"
      dependencies {
      -   // integrating log-service
      -   implementation "engineer.lynx.test2:lynx-service-log:0.0.1"
      }
      ```
    </Tab>

    <Tab label="Harmony">
      Replace the implementation of log service in `LynxServiceCenter` in the [integration documentation](/guide/start/integrate-with-existing-apps.md#platform=harmony) with your implementation.

      ```diff
      - LynxServiceCenter.registerService(LynxServiceType.Log, LynxLogService.instance);
      + LynxServiceCenter.registerService(LynxServiceType.Log, YourLogService.instance);
      ```

      And delete related dependencies

      ```diff title="oh-package.json5"
      "dependencies": {
      - "@lynx/lynx_log_service": "0.0.1",
      }
      ```
    </Tab>
  </Tabs>
</Steps>

**Compatibility Table**
**Query:** `lynx-native-api.lynx-service.lynx-service`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxService API




---
url: /api/lynx-native-api/lynx-template-resource-fetcher/fetch-template.md
---

# fetchTemplate

<APISummary />

`LynxEngine` internally calls this method to obtain the contents of Bundle and Lazy Bundle. The returned result type can contain `byte[]` or `TemplateBundle`.

## Syntax

### Android

```java
public abstract void fetchTemplate(
    LynxResourceRequest request, LynxResourceCallback<TemplateProviderResult> callback);
```

#### Parameters

- `request`: Request for the requiring content file.
- `callback`: Response with the requiring content file: byteArray or TemplateBundle

:::note

- This method must be implemented.

:::

### iOS

```objc
- (void)fetchTemplate:(LynxResourceRequest *_Nonnull)request
           onComplete:(LynxTemplateResourceCompletionBlock _Nonnull)callback;
```

#### Parameters

- `request`: Request for the requiring content file.
- `callback`: Response with the requiring content file: byteArray or TemplateBundle

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract fetchTemplate(request: LynxResourceRequest, callback: AsyncCallback<TemplateProviderResult>): void;
```

#### Parameters

- `request`: Request to obtain the contents of Bundle and Lazy Bundle
- `callback`: Response with the requiring content file in ArrayBuffer type.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-template-resource-fetcher.fetch-template`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** LynxEngine internally calls this method to obtain the contents of Bundle and Lazy Bundle. The returned result type can contain byte[] or TemplateBundle.




---
url: /api/lynx-native-api/lynx-update-meta.md
---

# LynxUpdateMeta

<APISummary />

LynxUpdateMeta is the metadata structure used by LynxView to update template data. It will serve as the input parameter for [UpdateData](/api/lynx-native-api/lynx-view/update-meta-data.md). Users can specify various parameters required for the update through LynxUpdateMeta, such as template data and globalProps, among others.

## Android:

### Field

LynxUpdateMeta has the following members:

- `updateData: TemplateData`: The content of the data to update the template;
- `globalProps: TemplateData`: The globalProps content for updating the template;

### Construction

On the Android platform, you need to use LynxUpdateMeta.Builder to construct a LynxUpdateMeta object:

```java
LynxUpdateMeta.Builder builder = new LynxUpdateMeta.Builder();
builder.setUpdatedData(data);
builder.setUpdatedGlobalProps(globalProps);
LynxUpdateMeta meta = builder.build();
```

## iOS

### Field

LynxUpdateMeta has the following members:

- `updateData: TemplateData`: The content of the data to update the template;
- `globalProps: TemplateData`: The globalProps content for updating the template;

### Construction

On the iOS platform, construct the LynxLoadMeta object as follows:

```objective-c
LynxUpdateMeta* meta = [LynxUpdateMeta init];
meta.data = nil;
meta.globalProps = nil;
```

## Harmony

### Field

MetaData has the following members:

- `templateData: TemplateData`: The content of the data to update the template;
- `globalProps: TemplateData`: The globalProps content for updating the template;

### Construction

On the HarmonyOS platform, construct the MetaData object as follows:

```typescript
metaData = new MetaData(
  new TemplateData('{"text":"TD"}'),
  new TemplateData({ "theme": "Light" }));
```

## Web

```ts
export type Cloneable<T = string | number | null | boolean | undefined> =
  | T
  | Record<string, T>
  | T[];

updateData(
  data: Cloneable,
  updateDataType: UpdateDataType,
  callback?: () => void,
): void;
updateGlobalProps(data: Cloneable): void;
```

#### Parameters

- `data`: Data to be updated, should be `structuredClone` compatible.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-update-meta`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |

**Description:** MetaData of LynxEngine updateProcess




---
url: /api/lynx-native-api/lynx-view-client/on-data-updated.md
---

# onDataUpdated

<APISummary />

Called when data update, but the view may not be updated.

## Syntax

### Android

```java
public void onDataUpdated();
```

### iOS

```objc
- (void)lynxViewDidUpdate:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

### Harmony

```typescript
public onDataUpdated(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-data-updated`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when data update, but the view may not be updated.




---
url: /api/lynx-native-api/lynx-view-client/on-destroy.md
---

# onDestroy

<APISummary />

Called after the page is destroyed.

## Syntax

### Android

```java
public void onDestroy();
```

:::note

- The callback executed in the main thread.

:::

### Harmony

```typescript
public onDestroy(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called after the page is destroyed.




---
url: /api/lynx-native-api/lynx-view-client/on-first-load-perf-ready.md
---

# onFirstLoadPerfReady

<APISummary />

Performance data statistics callback after the first load is completed.

## Syntax

### Android

```java
public void onFirstLoadPerfReady(LynxPerfMetric metric);
```

:::note

- The timing of the callback is not fixed due to differences in rendering threads, and should not be used as a starting point for any business side. The callback is in the main thread.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-first-load-perf-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Performance data statistics callback after the first load is completed.




---
url: /api/lynx-native-api/lynx-view-client/on-first-screen.md
---

# onFirstScreen

<APISummary />

Called when first screen layout completed.

## Syntax

### Android

```java
public void onFirstScreen();
```

### iOS

```objc
- (void)lynxViewDidFirstScreen:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

:::note

- You can get performance during loading process of the LynxView at this time.

:::

### Harmony

```typescript
public onFirstScreen(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-first-screen`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when first screen layout completed.




---
url: /api/lynx-native-api/lynx-view-client/on-fling.md
---

# onFling

<APISummary />

Called when inertial scrolling starts after releasing the finger.

## Syntax

### Android

```java
public void onFling(ScrollInfo info);
```

#### Parameters

- `info`: Contains scroll parameters, including the instance of the scrolling view, and the front-end specified id and name

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-fling`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when inertial scrolling starts after releasing the finger.




---
url: /api/lynx-native-api/lynx-view-client/on-flush-finish.md
---

# onFlushFinish

<APISummary />

Called when UI flush end in async render mode.

## Syntax

### Android

```java
public void onFlushFinish(FlushInfo flushInfo);
```

#### Parameters

- `flushInfo`: Contains the begin and end timings of the flush, and whether it is a synchronous flush.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-flush-finish`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when UI flush end in async render mode.




---
url: /api/lynx-native-api/lynx-view-client/on-key-event.md
---

# onKeyEvent

<APISummary />

Report all android key events with flag indicating whether has been handled.

## Syntax

### Android

```java
public void onKeyEvent(KeyEvent event, boolean handled);
```

#### Parameters

- `event`: The android key.
- `handled`: Indicate whether the event has been handled(consumed) by lynx.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-key-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Report all android key events with flag indicating whether has been handled.




---
url: /api/lynx-native-api/lynx-view-client/on-load-success.md
---

# onLoadSuccess

<APISummary />

Called when page load finish.

## Syntax

### Android

```java
public void onLoadSuccess();
```

### iOS

```objc
- (void)lynxView:(LynxView *)view didLoadFinishedWithUrl:(NSString *)url;
```

#### Parameters

- `view`: The LynxView instance.
- `url`: The page URL.

:::note

- This method is called once for each content loading request.

:::

### Harmony

```typescript
public onLoadSuccess(url: string): void;
```

#### Parameters

- `url`: The page url.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-load-success`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when page load finish.




---
url: /api/lynx-native-api/lynx-view-client/on-lynx-event.md
---

# onLynxEvent

<APISummary />

Report Lynx events that sended to frontend.

## Syntax

### Android

```java
public void onLynxEvent(LynxEventDetail detail);
```

#### Parameters

- `detail`: LynxEvent that will send to frontend, including eventName, lynxview, etc.

### iOS

```objc
- (void)onLynxEvent:(LynxEventDetail *)event;
```

#### Parameters

- `event`: LynxEvent that will send to frontend, including eventName, lynxview, etc.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-lynx-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Report Lynx events that sended to frontend.




---
url: /api/lynx-native-api/lynx-view-client/on-lynx-view-and-js-runtime-destroy.md
---

# onLynxViewAndJSRuntimeDestroy

<APISummary />

Called when lynx view and js runtime destroy.

## Syntax

### Android

```java
public void onLynxViewAndJSRuntimeDestroy();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-lynx-view-and-js-runtime-destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when lynx view and js runtime destroy.




---
url: /api/lynx-native-api/lynx-view-client/on-module-method-invoked.md
---

# onModuleMethodInvoked

<APISummary />

Called when module method invocation completed.

## Syntax

### Android

```java
public void onModuleMethodInvoked(String module, String method, int error_code);
```

#### Parameters

- `module`: Module name.
- `method`: Method name.
- `error_code`: Error code if module method invocation failed.

### iOS

```objc
- (void)lynxView:(LynxView *)view
    didInvokeMethod:(NSString *)method
           inModule:(NSString *)module
          errorCode:(int)code;
```

#### Parameters

- `view`: The LynxView instance.
- `method`: Method name.
- `module`: Module name.
- `code`: Error code if module method invocation failed.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-module-method-invoked`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when module method invocation completed.




---
url: /api/lynx-native-api/lynx-view-client/on-page-start.md
---

# onPageStart

<APISummary />

Called when page start loading.

## Syntax

### Android

```java
public void onPageStart(@Nullable String url);
```

#### Parameters

- `url`: The page URL

### iOS

```objc
- (void)lynxViewDidStartLoading:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

:::note

- This method is called once for each content loading request.

:::

### Harmony

```typescript
public onPageStarted(lynxContext: LynxContext, pipelineInfo: LynxPipelineInfo): void;
```

#### Parameters

- `lynxContext`: The LynxContext which has started loading
- `pipelineInfo`: The information about the pixel pipeline

:::note

- This method will be executed before the main process of lynx so do not execute overlycomplex logic in this method.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-page-start`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when page start loading.




---
url: /api/lynx-native-api/lynx-view-client/on-page-update.md
---

# onPageUpdate

<APISummary />

Called when page update.

## Syntax

### Android

```java
public void onPageUpdate();
```

### iOS

```objc
- (void)lynxViewDidPageUpdate:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

### Harmony

```typescript
public onPageUpdate(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-page-update`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when page update.




---
url: /api/lynx-native-api/lynx-view-client/on-performance-event.md
---

# onPerformanceEvent

<APISummary />

Notify the client that a performance event has been sent. It will be called every time a performance event is generated, including but not limited to container initialization, engine rendering, rendering metrics update, etc.

## Syntax

### Android

```java
public void onPerformanceEvent(@NonNull PerformanceEntry entry);
```

#### Parameters

- `entry`: The [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md) about the performance event.

### iOS

```objc
- (void)onPerformanceEvent:(nonnull LynxPerformanceEntry *)entry;
```

#### Parameters

- `entry`: The [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md) about the performance event.

### Harmony

```typescript
public onPerformanceEvent(entry: PerformanceEntry): void;
```

#### Parameters

- `entry`: The [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md) about the performance event.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-performance-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Notify the client that a performance event has been sent. It will be called every time a performance event is generated, including but not limited to container initialization, engine rendering, rendering metrics update, etc.




---
url: /api/lynx-native-api/lynx-view-client/on-piper-invoked.md
---

# onPiperInvoked

<APISummary />

Called when JSBridge invoked.

## Syntax

### Android

```java
public void onPiperInvoked(Map<String, Object> info);
```

#### Parameters

- `info`: JSBridge's information. `url: String`: Lynx's url; `module-name: String`: module's name; `method-name: String`: method's name; `params: List<Object>`: (Optional) other necessary parameters.

### iOS

```objc
- (void)onPiperInvoked:(NSDictionary *)info;
```

#### Parameters

- `info`: Piper's information. `url: NSString`: Lynx's url; `module-name: NSString`: module's name; `method-name: NSString`: method's name; `params: NSArray`: (Optional) other necessary parameters.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-piper-invoked`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when JSBridge invoked.




---
url: /api/lynx-native-api/lynx-view-client/on-received-error.md
---

# onReceivedError

<APISummary />

Called when error received.

## Syntax

### Android

```java
public void onReceivedError(LynxError error);
```

#### Parameters

- `error`: The type and information of the error.

### Harmony

```typescript
public onReceivedError(error: LynxError): void;
```

#### Parameters

- `error`: The type and information of the error.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when error received.




---
url: /api/lynx-native-api/lynx-view-client/on-received-java-error.md
---

# onReceivedJavaError

<APISummary />

Called when java error received.

## Syntax

### Android

```java
public void onReceivedJavaError(LynxError error);
```

#### Parameters

- `error`: The type and information of the error.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-java-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when java error received.




---
url: /api/lynx-native-api/lynx-view-client/on-received-js-error.md
---

# onReceivedJSError

<APISummary />

Called when JS error received.

## Syntax

### Android

```java
public void onReceivedJSError(LynxError jsError);
```

#### Parameters

- `jsError`: JS exception information.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-js-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when JS error received.




---
url: /api/lynx-native-api/lynx-view-client/on-received-native-error.md
---

# onReceivedNativeError

<APISummary />

Called when C++ layer error received.

## Syntax

### Android

```java
public void onReceivedNativeError(LynxError nativeError);
```

#### Parameters

- `nativeError`: Native exception information.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-native-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when C++ layer error received.




---
url: /api/lynx-native-api/lynx-view-client/on-report-component-info.md
---

# onReportComponentInfo

<APISummary />

Return the used component tagName.

## Syntax

### Android

```java
public void onReportComponentInfo(Set<String> mComponentSet);
```

#### Parameters

- `mComponentSet`: The set of component tagName.

### iOS

```objc
- (void)lynxView:(LynxView *)view didReportComponentInfo:(NSSet<NSString *> *)componentSet;
```

#### Parameters

- `view`: The LynxView instance.
- `componentSet`: The set of component tagName.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-report-component-info`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Return the used component tagName.




---
url: /api/lynx-native-api/lynx-view-client/on-runtime-ready.md
---

# onRuntimeReady

<APISummary />

Called when JS environment preparation completed.

## Syntax

### Android

```java
public void onRuntimeReady();
```

:::note

- The callback is in an asynchronous thread.

:::

### iOS

```objc
- (void)lynxViewDidConstructJSRuntime:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

### Harmony

```typescript
public onRuntimeReady(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-runtime-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Called when JS environment preparation completed.




---
url: /api/lynx-native-api/lynx-view-client/on-scroll-start.md
---

# onScrollStart

<APISummary />

Called when the UI start scrolling.

## Syntax

### Android

```java
public void onScrollStart(ScrollInfo info);
```

#### Parameters

- `info`: Contains scroll parameters, including the instance of the scrolling view, and the front-end specified id and name.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-scroll-start`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when the UI start scrolling.




---
url: /api/lynx-native-api/lynx-view-client/on-scroll-stop.md
---

# onScrollStop

<APISummary />

Called when the UI finished scrolling.

## Syntax

### Android

```java
public void onScrollStop(ScrollInfo info);
```

#### Parameters

- `info`: Contains scroll parameters, including the instance of the scrolling view, and the front-end specified id and name.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-scroll-stop`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when the UI finished scrolling.




---
url: /api/lynx-native-api/lynx-view-client/on-tasm-finished-by-native.md
---

# onTASMFinishedByNative

<APISummary />

Called when native layout finish in ui or most\_on\_tasm mode, or diff finish in multi\_thread mode.

## Syntax

### Android

```java
public void onTASMFinishedByNative();
```

### iOS

```objc
- (void)lynxViewOnTasmFinishByNative:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-tasm-finished-by-native`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Called when native layout finish in ui or most_on_tasm mode, or diff finish in multi_thread mode.




---
url: /api/lynx-native-api/lynx-view-client/on-template-bundle-ready.md
---

# onTemplateBundleReady

<APISummary />

Provide a reusable TemplateBundle after template is decode.

## Syntax

### Android

```java
public void onTemplateBundleReady(@NonNull TemplateBundle bundle);
```

#### Parameters

- `bundle`: The recycled template bundle, it is nonnull but could be invalid.

:::note

- This callback is disabled by default, and you can enable it through the DUMP\_ELEMENT option or RECYCLE\_TEMPLATE\_BUNDLE option in LynxLoadMeta.

:::

### iOS

```objc
- (void)onTemplateBundleReady:(LynxTemplateBundle *)bundle;
```

#### Parameters

- `bundle`: the recycled template bundle, it is nonnull but could be invalid

:::note

- This callback is disabled by default, and you can enable it through the enableRecycleTemplateBundle option in LynxLoadMeta.

:::

### Harmony

```typescript
public onTemplateBundleReady(bundle: TemplateBundle): void;
```

#### Parameters

- `bundle`: The recycled template bundle, it is nonnull but could be invalid.

:::note

- This callback is disabled by default, and you can enable it through theDUMP\_ELEMENT option or RECYCLE\_TEMPLATE\_BUNDLE option in LynxLoadMeta.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-template-bundle-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Provide a reusable TemplateBundle after template is decode.




---
url: /api/lynx-native-api/lynx-view-client/on-update-data-without-change.md
---

# onUpdateDataWithoutChange

<APISummary />

If there is no need to update the UI after calling [`updateData`](/api/lynx-native-api/lynx-view/update-meta-data.md), this method is called back.

## Syntax

### Harmony

```typescript
public onUpdateDataWithoutChange(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-update-data-without-change`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** If there is no need to update the UI after calling updateData, this method is called back.




---
url: /api/lynx-native-api/lynx-view-client/on-update-perf-ready.md
---

# onUpdatePerfReady

<APISummary />

Performance data statistics callback after the interface update is completed.

## Syntax

### Android

```java
public void onUpdatePerfReady(LynxPerfMetric metric);
```

:::note

- The timing of the callback is not fixed due to differences in rendering threads, and should not be used as a starting point for any business side. The callback is in the main thread.

:::

### iOS

```objc
- (void)lynxView:(LynxView *)view didReceiveUpdatePerf:(LynxPerformance *)perf;
```

#### Parameters

- `view`: The LynxView instance.

:::note

- The timing of the callback is not fixed due to differences in rendering threads, and should not be used as a starting point for any business side. The callback is in the main thread.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-update-perf-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Performance data statistics callback after the interface update is completed.




---
url: /api/lynx-native-api/lynx-view.md
---




---
url: /api/lynx-native-api/lynx-view/add-lynx-view-client.md
---

# addLynxViewClient

<APISummary />

Register lifecycle event observer for `LynxView`.

## Syntax

### Android

```java
public void addLynxViewClient(LynxViewClient client);
```

#### Parameters

- `client`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the `LynxView` lifecycle

### iOS

```objc
- (void)addLifecycleClient:(nonnull id<LynxViewBaseLifecycle>)lifecycleClient;
```

#### Parameters

- `lifecycleClient`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the `LynxView` lifecycle.

### Harmony

#### Field

LynxView has clients member:

- `clients: LynxViewClient[]`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the `LynxView` lifecycle.

On the HarmonyOS platfrom, you need to pass your implemented LynxViewClient as a parameter during the initialization of LynxView:

```typescript
@Entry
@Component
struct Index {
  private clients: EntryLynxClient[] = [new EntryLynxClient()];

  build() {
    Column() {
      LynxView({
        clients: this.clients,
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.add-lynx-view-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** register lifecycle observer for lynxView




---
url: /api/lynx-native-api/lynx-view/destroy.md
---

# destroy

<APISummary />

After `LynxView` becomes unavailable, you need to actively call this method to release the `LynxView` memory, otherwise there will be a memory leak.

## Syntax

### Android

```java
public void destroy();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** manually destroy lynxView instance




---
url: /api/lynx-native-api/lynx-view/enable-auto-layout.md
---

# enableAutoLayout

When enabled, the size calculated by iOS AutoLayout will take effect on LynxView.

## Syntax

### iOS

```objc
@property(nonatomic, assign) bool enableAutoLayout;
```

#### Parameter Description

`enableAutoLayout`: Boolean switch

- The default value is `false`. When the value is `false`, LynxView will ignore the size results calculated by the AutoLayout engine.
- When the value is `true`, LynxView will use the size results calculated by the AutoLayout engine.

#### Example Code

```objc
- (void)setupMainLynxView {
  self.mainLynxView.translatesAutoresizingMaskIntoConstraints = NO;
  [NSLayoutConstraint activateConstraints:@[
    [self.mainLynxView.topAnchor constraintEqualToAnchor:self.autoLayoutSwitch.bottomAnchor
                                                constant:20],
    [self.mainLynxView.leadingAnchor constraintEqualToAnchor:self.view.leadingAnchor],
    [self.mainLynxView.trailingAnchor constraintEqualToAnchor:self.view.trailingAnchor],
    [self.mainLynxView.bottomAnchor
        constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor]
  ]];

  self.mainLynxView.enableAutoLayout = true;
}
```

## Notes

When enabled, `LynxView` will automatically use the results calculated by the AutoLayout engine as the view size during layout. If `updateViewport` was previously used to set the view size, the settings from `updateViewport` will be overwritten.

Related documentation: Please refer to [updateViewport](/api/lynx-native-api/lynx-view/update-viewport.md).



---
url: /api/lynx-native-api/lynx-view/find-ui-by-id-selector.md
---

# findUIByIdSelector

<APISummary />

Find `LynxUI` nodes based on the idSelector attribute.

## Syntax

### Android

```java
public LynxBaseUI findUIByIdSelector(String id);
```

#### Parameters

- `id`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the idSelector attribute.

### iOS

```objc
- (nullable LynxUI *)uiWithIdSelector:(nonnull NSString *)idSelector;
```

#### Parameters

- `idSelector`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the idSelector attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-ui-by-id-selector`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** find ui by idselector




---
url: /api/lynx-native-api/lynx-view/find-ui-by-name.md
---

# findUIByName

<APISummary />

Find `LynxUI` nodes based on the name attribute.

## Syntax

### Android

```java
public LynxBaseUI findUIByName(String name);
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the name attribute.

### iOS

```objc
- (nullable LynxUI *)uiWithName:(nonnull NSString *)name;
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the name attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-ui-by-name`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** find ui by name




---
url: /api/lynx-native-api/lynx-view/find-view-by-id-selector.md
---

# findViewByIdSelector

<APISummary />

Find `UIView` based on `idSelector` property.

## Syntax

### Android

```java
public View findViewByIdSelector(String id);
```

#### Parameters

- `id`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the idSelector attribute.

### iOS

```objc
- (nullable UIView *)viewWithIdSelector:(nonnull NSString *)idSelector;
```

#### Parameters

- `idSelector`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the idSelector attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-view-by-id-selector`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** find view by idselector




---
url: /api/lynx-native-api/lynx-view/find-view-by-name.md
---

# findViewByName

<APISummary />

Find `UIView` based on name attribute.

## Syntax

### Android

```java
public View findViewByName(String name);
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the name attribute.

### iOS

```objc
- (nullable UIView *)findViewWithName:(nonnull NSString *)name;
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the name attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-view-by-name`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** find view by name




---
url: /api/lynx-native-api/lynx-view/load-template.md
---

# loadTemplate

<APISummary />

Using [`LynxLoadMeta`](/api/lynx-native-api/lynx-load-meta.md) to render `LynxView`, it is the main entrance for the client to load `Lynx` templates.

## Syntax

### Android

```java
public void loadTemplate(@NonNull LynxLoadMeta meta);
```

#### Parameters

- `meta`: Lynx template loads metadata, and developers use this data structure to specify optional data loaded by the template.

### iOS

```objc
- (void)loadTemplate:(nonnull LynxLoadMeta *)meta;
```

#### Parameters

- `meta`: Lynx template loads metadata, and developers use this data structure to specify optional data loaded by the template.

### Harmony

LynxView has the following members:

- `url: String `: Template file path.
- `buffer: ArrayBuffer`: The binary file data of the template.
- `templateBundle: TemplateBundle`: [TemplateBundle](/api/lynx-native-api/template-bundle.md) object parsed in advance by the template's binary file data.
- `metaData: MetaData`: Initial data specified by the client during the first screen loading process.
- `loadOption: LynxLoadOption`: Additional configuration information when loading templates.

```typescript
@Entry
@Component
struct Index {
  private url: string = 'playground/main.lynx.bundle';
  private buffer: ArrayBuffer = getTemplateBuffer();
  private metaData = new MetaData(
    new TemplateData('{"text":"TD"}'),
    new TemplateData({ "theme": "Light" }));

  build() {
    Column() {
      LynxView({
        url: this.url,
        buffer: this.buffer,
        metadata: this.metaData,
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```

### Web

```typescript
const lynxView = document.createElement('lynx-view');
lynxView.url = 'path/to/your/template.bundle';
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.load-template`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | use the <code>url</code> property; ⚠️ Partial implementation |

**Description:** load a lynx template file by LynxView.




---
url: /api/lynx-native-api/lynx-view/lynx-view.md
---

# `<lynx-view>`

<APISummary />

`<lynx-view>` is a container component that loads and displays Lynx templates. It can be used in web applications to render Lynx templates.

After completing the above integration, you can achieve more flexible interaction control through the APIs provided by Lynx for Web. Here is a detailed description of the core APIs:

## lynx-view

### Attributes

| Name                        | Required | Description                                                                                                                                           |
| :-------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| url                         | Yes      | URL of the Rspeedy output (URLs of other chunks will be automatically injected and launched during compilation)                                       |
| globalProps                 | No       | [GlobalProps](/api/lynx-api/lynx/lynx-global-props.md) for card initialization                                                                        |
| initData                    | No       | InitData for card initialization                                                                                                                      |
| overrideLynxTagToHTMLTagMap | No       | Custom mapping relationship from Lynx tags to HTML tags. React Components are not supported, only HTMLElements (can be web components or native tags) |

### Properties

#### nativeModulesMap

Custom [NativeModule](/guide/use-native-modules.md) where key is the module name and value is the module implementation (an ESM URL):

```ts
type NativeModulesMap = Record<string, string>;
```

Example:

```ts
const nativeModulesMap = {
  CustomModule: URL.createObjectURL(
    new Blob(
      [
        `export default function(NativeModules, NativeModulesCall) {
    return {
      async getColor(data, callback) {
        const color = await NativeModulesCall('getColor', data);
        callback(color);
      },
    }
  };`,
      ],
      { type: 'text/javascript' },
    ),
  ),
};
lynxView.nativeModulesMap = nativeModulesMap;
```

#### onNativeModulesCall

Entry point for handling NativeModules (JSB, etc.) related calls:

```ts
(name: string, data: any, moduleName: string) => Promise<any> | any;
```

Example:

```ts
// Handle NativeModule.bridge.call('request')
lynxView.onNativeModulesCall = (name, data, moduleName) => {
  if (moduleName === 'bridge') {
    if (name === 'request') {
      // ...

      // return data will be automatically processed as callback data
      return {};
    }
  }
};
```

#### customTemplateLoader

Allows users to implement custom template loading functionality (default is fetch):

```ts
lynxView.customTemplateLoader = (url) => {
  return await(
    await fetch(url, {
      method: 'GET',
    }),
  ).json();
};
```

### Events

#### error

Error message notification:

```ts
type LynxError = CustomEvent<{
  error: Error;
  sourceMap: {
    offset: {
      // Line offset
      line: number;
      // Column offset
      col: number;
    };
  };
  release: string;
  fileName: 'lepus.js' | 'app-service.js';
}>;

lynxView.addEventListener('error', (err: LynxError) => {
  // ...
});
```

### Methods

#### updateData

[See details](/api/lynx-native-api/lynx-view/update-meta-data.md)

```ts
export type Cloneable<T = string | number | null | boolean | undefined> =
  | T
  | Record<string, T>
  | T[];

updateData(
  data: Cloneable,
  updateDataType: UpdateDataType,
  callback?: () => void,
): void
```

#### updateGlobalProps

[See details](/api/lynx-api/main-thread/lynx-global-props.md)

```ts
updateGlobalProps(data: Cloneable): void;
```

#### sendGlobalEvent

[See details](/api/lynx-native-api/lynx-view/send-global-event.md)

```ts
sendGlobalEvent(eventName: string, params: Cloneable[]): void;
```

### Width and Height

:::note
The internal layout of lynx-view will be forced out of the external layout flow
:::

We will force all lynx-view elements to apply [CSS Containment](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment).

That is, by default, you need to set a width and height for lynx-view. The width and height can be allocated by `flex-grow` or specified as a percentage, but cannot be "stretched". Setting width and height is a strongly recommended practice and also a best practice for performance.

In some cases where you really need the width or height to be determined by the content of lynx-view, you can set `height="auto"` or `width="auto"` to enable the automatic width/height listener. In this case, the internal layout of lynx-view remains independent of the external layout flow.

## Compatibility

The recommended configuration is: **Chrome > 118, Safari > 18, Firefox NSR**

If you want to support browsers with Chrome \< 118 and Safari \< 18, you need to do the following:

1. Import the compatibility plugin:

```ts
import '@lynx-js/web-elements-compat/LinearContainer';
```

2. Additionally compile the `@lynx-js` dependencies. If your project uses Rsbuild, modify the configuration as follows:

```ts
// rsbuild.config.ts
export default {
  source: {
    include: [/@lynx-js/],
  },
  output: {
    polyfill: 'usage',
  },
};
```

## FAQ

### Runtime error: `Uncaught SecurityError: Failed to construct 'Worker': Script at 'xxx' cannot be accessed from origin 'xxx'.`

This is because Worker loading remote scripts needs to comply with the [Same-Origin Policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy), and the JS resources of the project are generally deployed on CDN, causing cross-origin issues.

This can be solved by introducing [remote-web-worker](https://github.com/jantimon/remote-web-worker):

```ts
// The import position must be before @lynx-js/web-core
import 'remote-web-worker';

import '@lynx-js/web-core';
import '@lynx-js/web-core/index.css';
import '@lynx-js/web-elements/all';
import '@lynx-js/web-elements/index.css';
document.body.innerHTML = `
<lynx-view
    style="height:100vh; width:100vw;"
    url="http://localhost:3000/main/index.main.bundle"
>
</lynx-view>`;
```

### Performance Optimization

We provide an RSBuild plugin for performance optimization. You can introduce [this plugin](https://www.npmjs.com/package/@lynx-js/web-platform-rsbuild-plugin) in your web project.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.lynx-view-custom-element`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ✅ Yes | - |

**Description:** <code>lynx-view</code> The custom element of LynxView.




---
url: /api/lynx-native-api/lynx-view/reload.md
---

# reload

<APISummary />

Reload the current page.

## Syntax

### Web

```ts
reload(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.reload`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ✅ Yes | - |

**Description:** reload lynx page.




---
url: /api/lynx-native-api/lynx-view/remove-lynx-view-client.md
---

# removeLynxViewClient

<APISummary />

Remove `LynxView` lifecycle event monitoring.

## Syntax

### Android

```java
public void removeLynxViewClient(LynxViewClient client);
```

#### Parameters

- `client`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the LynxView life cycle.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.remove-lynx-view-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** remove lifecycle observer of lynxView




---
url: /api/lynx-native-api/lynx-view/send-global-event.md
---

# sendGlobalEvent

<APISummary />

Send global events to the front end through the client, and the front end can listen to the event through `GlobalEventEmitter`.

## Syntax

### Android

```java
public void sendGlobalEvent(String name, JavaOnlyArray params);
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by global events.

### iOS

```objc
- (void)sendGlobalEvent:(nonnull NSString *)name withParams:(nullable NSArray *)params;
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by global events.

### Web

```ts
sendGlobalEvent(eventName: string, params: Cloneable[]): void;
```

#### Parameters

- `eventName`: Global event name.
- `params`: Parameters carried by global events.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.send-global-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ✅ Yes | - |

**Description:** send global event to js enviroment




---
url: /api/lynx-native-api/lynx-view/set-extra-timing.md
---

# setExtraTiming

<APISummary />

This interface is used to supplement key performance data before loading the Lynx page, specifically including the following items from [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md):

- Page open time (`openTime`)
- Timestamp for the start of preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) (`prepareTemplateStart`)
- Timestamp for the end of preparing the TemplateBundle (`prepareTemplateEnd`)
- Timestamp for the start of [container](/guide/spec.md#container) initialization (`containerInitStart`)
- Timestamp for the end of container initialization (`containerInitEnd`)

Upon successfully updating all timestamps using this interface, the `InitContainerEntry` performance event will be triggered. Depending on the timing of the configuration, it may also trigger the calculation of `fcp`, `totalFcp`, `actualFmp`, and `totalActualFmp` metrics, along with dispatching new performance events for [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).

:::caution
Timestamps within extraTiming cannot be overwritten, meaning that multiple calls to this interface attempting to repeatedly update a timestamp will yield no effect.
:::

## Syntax

### Android

```java
public void setExtraTiming(TimingHandler.ExtraTimingInfo extraTiming);
```

#### Parameters

- `extraTiming`: Used to supplement key performance data before loading the Lynx page.

The specific definition of `ExtraTimingInfo` is as follows:

```java
public static class ExtraTimingInfo {
    // Page open time, corresponds to openTime in InitContainerEntry.
    public long mOpenTime = 0;
    // Timestamp for the start of preparing the TemplateBundle, corresponds to prepareTemplateStart in InitContainerEntry.
    public long mPrepareTemplateStart = 0;
    // Timestamp for the end of preparing the TemplateBundle, corresponds to prepareTemplateEnd in InitContainerEntry.
    public long mPrepareTemplateEnd = 0;
    // Timestamp for the start of container initialization, corresponds to containerInitStart in InitContainerEntry.
    public long mContainerInitStart = 0;
    // Timestamp for the end of container initialization, corresponds to containerInitEnd in InitContainerEntry.
    public long mContainerInitEnd = 0;
}
```

### iOS

```objc
- (void)setExtraTiming:(LynxExtraTiming *_Nonnull)timing;
```

#### Parameters

- `timing`: Used to supplement key performance data before loading the Lynx page.

The specific definition of `LynxExtraTiming` is as follows:

```objc
@interface LynxExtraTiming : NSObject

// Page open time, corresponds to openTime in InitContainerEntry.
@property(nonatomic, assign) uint64_t openTime;
// Timestamp for the start of preparing the TemplateBundle, corresponds to prepareTemplateStart in InitContainerEntry.
@property(nonatomic, assign) uint64_t prepareTemplateStart;
// Timestamp for the end of preparing the TemplateBundle, corresponds to prepareTemplateEnd in InitContainerEntry.
@property(nonatomic, assign) uint64_t prepareTemplateEnd;
// Timestamp for the start of container initialization, corresponds to containerInitStart in InitContainerEntry.
@property(nonatomic, assign) uint64_t containerInitStart;
// Timestamp for the end of container initialization, corresponds to containerInitEnd in InitContainerEntry.
@property(nonatomic, assign) uint64_t containerInitEnd;

@end
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.set-extra-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** set extra timing from outside.




---
url: /api/lynx-native-api/lynx-view/update-font-scale.md
---

# updateFontScale

<APISummary />

Changing the font scaling ratio in client settings will automatically change the text size.

## Syntax

### Android

```java
public void updateFontScale(float scale);
```

#### Parameters

- `scale`: The new font scaling ratio.

### iOS

```objc
- (void)updateFontScale:(CGFloat)scale;
```

#### Parameters

- `scale`: The new font scaling ratio.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.update-font-scale`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** update font scale of lynxView




---
url: /api/lynx-native-api/lynx-view/update-meta-data.md
---

# updateMetaData

<APISummary />

Using [LynxUpdateMeta](/api/lynx-native-api/lynx-update-meta.md) to update `LynxView`, it is the main entrance for the client to update template data.

## Syntax

### Android

```java
public void updateMetaData(LynxUpdateMeta meta);
```

#### Parameters

- `meta`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template.

### iOS

```objc
- (void)updateMetaData:(nonnull LynxUpdateMeta *)meta;
```

#### Parameters

- `meta`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template.

### Web

```ts
export type Cloneable<T = string | number | null | boolean | undefined> =
  | T
  | Record<string, T>
  | T[];

updateData(
  data: Cloneable,
  updateDataType: UpdateDataType,
  callback?: () => void,
): void;
updateGlobalProps(data: Cloneable): void;
```

#### Parameters

- `data`: Data to be updated, should be `structuredClone` compatible.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.update-meta-data`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** update lynx page by new data.




---
url: /api/lynx-native-api/lynx-view/update-viewport.md
---

# updateViewport

<APISummary />

The client updates the `LynxView` view size.

## Syntax

### Android

```java
public void updateViewport(int widthMeasureSpec, int heightMeasureSpec);
```

#### Parameters

- `widthMeasureSpec`: Current `LynxView` width.
- `heightMeasureSpec`: Current `LynxView` height.

### iOS

```objc
- (void)updateViewportWithPreferredLayoutWidth:(CGFloat)preferredLayoutWidth
                         preferredLayoutHeight:(CGFloat)preferredLayoutHeight
                                    needLayout:(BOOL)needLayout;
```

#### Parameters

- `preferredLayoutWidth`: Current `LynxView` width.
- `preferredLayoutHeight`: Current `LynxView` height.
- `needLayout`: Whether layout needs to be triggered.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.update-viewport`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** update viewport of lynxView




---
url: /api/lynx-native-api/template-bundle.md
---




---
url: /api/lynx-native-api/template-bundle/from-template-async-with-option.md
---

# fromTemplateAsyncWithOption

<APISummary />

Asynchronously creates a TemplateBundle from a template binary data with options. This method avoids blocking the main thread.

## Syntax

### Harmony

```typescript
public static async fromTemplateAsyncWithOption(template: ArrayBuffer, option: TemplateBundleOption): Promise<TemplateBundle>;
```

#### Parameters

- `template`: The template binary content.
- `option`: The TemplateBundleOption object.

#### Return

- A promise that resolves with the new TemplateBundle object.

:::note

- Due to ArkTS being restricted to run on the app’s main thread, we provide an asynchronous TemplateBundle creation API to reduce blocking time from main-thread I/O operations. On other platforms, developers can decide whether to run on a background thread without requiring a special asynchronous API.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.from-template-async-with-option`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.6 | - |
| Web | ❌ No | - |

**Description:** Asynchronously creates a TemplateBundle from a template binary data with options. This method avoids blocking the main thread.




---
url: /api/lynx-native-api/template-bundle/from-template-async.md
---

# fromTemplateAsync

<APISummary />

Asynchronously creates a TemplateBundle from a template binary data. This method avoids blocking the main thread.

## Syntax

### Harmony

```typescript
public static async fromTemplateAsync(template: ArrayBuffer): Promise<TemplateBundle>;
```

#### Parameters

- `template`: ArrayBuffer, a buffer of template binary data.

#### Return

- A promise that resolves with a new TemplateBundle object.

:::note

- Due to ArkTS being restricted to run on the app’s main thread, we provide an asynchronous TemplateBundle creation API to reduce blocking time from main-thread I/O operations. On other platforms, developers can decide whether to run on a background thread without requiring a special asynchronous API.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.from-template-async`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.6 | - |
| Web | ❌ No | - |

**Description:** Asynchronously creates a TemplateBundle from a template binary data. This method avoids blocking the main thread.




---
url: /api/lynx-native-api/template-bundle/from-template.md
---

# fromTemplate

<APISummary />

Input Lynx template binary content and return the parsed `TemplateBundle` object.

## Syntax

### Android

```java
public static TemplateBundle fromTemplate(byte[] template);
```

#### Parameters

- `template`: Template binary content.

#### Return

- The `TemplateBundle` object.

:::note

- When the input `template` is `null`, this method returns `null` directly.
- When the input `template` is not a correct `Lynx` template data, an invalid `TemplateBundle` is returned.

:::

### iOS

```objc
- (instancetype _Nullable)initWithTemplate:(nonnull NSData *)tem;
```

#### Parameters

- `tem`: Template binary content.

#### Return

- The `TemplateBundle` object.

:::note

- When the input `tem` is not a correct `Lynx` template data, or is `nil`, an invalid `TemplateBundle` is returned

:::

### Harmony

```typescript
public static async fromTemplate(template: ArrayBuffer): Promise<TemplateBundle>;
```

#### Parameters

- `template`: Template binary content.

#### Return

- TemplateBundle in promise.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.from-template`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Input Lynx template binary content and return the parsed TemplateBundle object.




---
url: /api/lynx-native-api/template-bundle/get-error-message.md
---

# getErrorMessage

<APISummary />

When `TemplateBundle` is an invalid object, use this method to obtain the exception information that occurred during template parsing.

## Syntax

### Android

```java
public String getErrorMessage();
```

#### Return

- The exception information.

### iOS

```objc
- (NSString *_Nullable)errorMsg;
```

#### Return

- The exception information, if `nil` is returned, it proves that the `LynxTemplateBundle` is normal

### Harmony

```typescript
public getErrorMessage(): string;
```

#### Return

- The exception information during template parsing.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.get-error-message`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** When TemplateBundle is an invalid object, use this method to obtain the exception information that occurred during template parsing.




---
url: /api/lynx-native-api/template-bundle/get-extra-info.md
---

# getExtraInfo

<APISummary />

Read the content of the `extraInfo` field configured in the `pageConfig` of the front-end template.

## Syntax

### Android

```java
public Map<String, Object> getExtraInfo();
```

#### Return

- When the front-end does not configure `extraInfo` or is called on an empty `TemplateBundle` object, it returns `null`, else it returns the `extraInfo` field.

### iOS

```objc
- (NSDictionary *_Nullable)extraInfo;
```

#### Return

- When the front-end does not configure `extraInfo` or is called on an empty `TemplateBundle` object, it returns `nil`, else it returns the `extraInfo` field.

### Harmony

```typescript
public getExtraInfo(): Map<string, Object>;
```

#### Return

- When the front-end does not configure extraInfo or is called on an empty TemplateBundle object, it returns null.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.get-extra-info`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Read the content of the extraInfo field configured in the pageConfig of the front-end template.




---
url: /api/lynx-native-api/template-bundle/get-template-size.md
---

# getTemplateSize

<APISummary />

Get the size of current template.

## Syntax

### Harmony

```typescript
public getTemplateSize(): number;
```

#### Return

- Template size.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.get-template-size`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Get the size of current template.




---
url: /api/lynx-native-api/template-bundle/is-element-bundle-valid.md
---

# isElementBundleValid

<APISummary />

Whether the TemplateBundle contains a Valid ElementBundle.

## Syntax

### Android

```java
public boolean isElementBundleValid();
```

#### Return

- True if valid, else false.

### iOS

```objc
- (BOOL)isElementBundleValid;
```

#### Return

- True if the TemplateBundle contains a Valid ElementBundle, otherwise false.

### Harmony

```typescript
public isElementBundleValid(): boolean;
```

#### Return

- True if valid, else false.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.is-element-bundle-valid`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Whether the TemplateBundle contains a Valid ElementBundle.




---
url: /api/lynx-native-api/template-bundle/is-valid.md
---

# isValid

<APISummary />

Determines whether the current `TemplateBundle` object is valid.

## Syntax

### Android

```java
public boolean isValid();
```

#### Return

- `true` if the current `TemplateBundle` object is valid, else `false`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.is-valid`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Determines whether the current TemplateBundle object is valid.




---
url: /api/lynx-native-api/template-bundle/post-js-cache-generation-task.md
---

# postJsCacheGenerationTask

<APISummary />

Start a sub-thread task to generate the `js code cache` of the current template.

## Syntax

### Android

```java
public void postJsCacheGenerationTask(String bytecodeSourceUrl, boolean useV8);
```

#### Parameters

- `bytecodeSourceUrl`: The `url` of the current template.
- `useV8`: Whether to generate `V8 Code Cache`, otherwise generate `QuickJS Code Cache`.

### iOS

```objc
- (void)postJsCacheGenerationTask:(nonnull NSString *)bytecodeSourceUrl;
```

#### Parameters

- `bytecodeSourceUrl`: The source url of the template.

### Harmony

```typescript
public postJsCacheGenerationTask(bytecodeSourceUrl: string, useV8: boolean): void;
```

#### Parameters

- `bytecodeSourceUrl`: The url of the current template.
- `useV8`: Whether to generate V8 Code Cache, otherwise generate QuickJS Code Cache.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.post-js-cache-generation-task`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Start a sub-thread task to generate the js code cache of the current template.




---
url: /api/lynx-native-api/template-bundle/release.md
---

# release

<APISummary />

Release the `Native` memory held by the current `TemplateBundle` object. After executing the `release` method, the `TemplateBundle` will become the `inValid` state.

## Syntax

### Android

```java
public void release();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.release`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Release the Native memory held by the current TemplateBundle object. After executing the release method, the TemplateBundle will become the inValid state.




---
url: /api/lynx-native-api/template-data/constructor.md
---

# constructor

<APISummary />

Input data in string, key-value or json format and return the parsed `TemplateData` object.

## Syntax

### Harmony

```typescript
constructor(input: string | Record<string, Object> | Object, processor: string);
```

#### Parameters

- `input`: String, key-value or json type data.
- `processor`: Data processor.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.constructor`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Input data in string, key-value or json format and return the parsed TemplateData object.




---
url: /api/lynx-native-api/template-data/data.md
---

# data

<APISummary />

Get the data in `TemplateData` object.

## Syntax

### Harmony

```typescript
data(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.data`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Get the data in TemplateData object.




---
url: /api/lynx-native-api/template-data/from-map.md
---

# fromMap

<APISummary />

Input data in key-value format and return the parsed `TemplateData` object.

## Syntax

### Android

```java
public static TemplateData fromMap(Map<String, Object> data);
```

#### Parameters

- `data`: `Map` type data.

#### Return

- `TemplateData` constructed by `data`.

### iOS

```objc
- (instancetype)initWithDictionary:(NSDictionary *)dictionary;
```

#### Parameters

- `dictionary`: `NSDictionary*` type data.

#### Return

- `TemplateData` constructed by `data`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.from-map`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Input data in key-value format and return the parsed TemplateData object.




---
url: /api/lynx-native-api/template-data/from-string.md
---

# fromString

<APISummary />

Input data in json and return the parsed `TemplateData` object.

## Syntax

### Android

```java
public static TemplateData fromString(String json);
```

#### Parameters

- `json`: `String` type data in json format.

#### Return

- `TemplateData` constructed by `json`.

### iOS

```objc
- (instancetype)initWithJson:(NSString *)json;
```

#### Parameters

- `json`: `NSString*` type data in json format.

#### Return

- `TemplateData` constructed by `json`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.from-string`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Input data in json and return the parsed TemplateData object.




---
url: /api/lynx-native-api/template-data/mark-state.md
---

# markState

<APISummary />

Mark the current TemplateData with the associated dataProcessor name. When this TemplateData is used in [UpdateData](/api/lynx-native-api/lynx-view/update-meta-data.md), the corresponding dataProcessor will be found based on this name for data preprocessing.

## Syntax

### Android

```java
public void markState(String name);
```

#### Parameters

- `name`: Marked name.

### iOS

```objc
- (void)markState:(NSString *)name;
```

#### Parameters

- `name`: Marked name.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.mark-state`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Mark the current TemplateData with the associated dataProcessor name. When this TemplateData is used in UpdateData, the corresponding dataProcessor will be found based on this name for data preprocessing.




---
url: /api/lynx-native-api/template-data/merge.md
---

# merge

<APISummary />

Merge the incoming data with the current data.

## Syntax

### Harmony

```typescript
merge(data: string | Record<string, Object> | Object): void;
```

#### Parameters

- `data`: Incoming data in string, key-value or json format.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.merge`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |

**Description:** Merge the incoming data with the current data.




---
url: /api/lynx-native-api/trace-event.md
---

# TraceEvent

<APISummary />

`TraceEvent` is a performance instrumentation utility provided by Lynx. Developers can use TraceEvent to flexibly insert trace points in client-side code, recording the execution timing and duration of key functions, tasks, rendering processes, and more.

## Android

### beginSection

Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```java
public static void beginSection(String category, String name)
public static void beginSection(String category, String name, Map<String, String> args)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args (optional)

Custom arguments for the trace event.

#### Examples

```java
TraceEvent.beginSection("render", "measure-layout");
// ... your code ...
TraceEvent.endSection("render", "measure-layout");

// With custom arguments
Map<String, String> args = new HashMap();
args.put("component", "Image");
args.put("size", "large");
TraceEvent.beginSection("render", "draw-image", args);
// ... your code ...
TraceEvent.endSection("render", "draw-image");
```

### endSection

Marks the end of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```java
public static void endSection(String category, String name)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### Examples

```java
TraceEvent.beginSection("logic", "parse-data");
// ... your code ...
TraceEvent.endSection("logic", "parse-data");
```

### instant

Marks an instant trace event.

```java
public static void instant(String category, String name)
public static void instant(String category, String name, Map<String, String> args)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```java
TraceEvent.instant("network", "request-started");

// With custom arguments
Map<String, String> args = new HashMap<>();
args.put("url", "https://example.com");
args.put("method", "GET");
TraceEvent.instant("network", "request-finished", args);
```

## iOS

### beginSection

Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```objective-c
+ (void)beginSection:(NSString *)category withName:(NSString *)name
+ (void)beginSection:(NSString *)category withName:(NSString *)name debugInfo:(NSDictionary *)args
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```objective-c
[LynxTraceEvent beginSection:@"render" withName:@"measure-layout"];
// ... your code ...
[LynxTraceEvent endSection:@"render" withName:@"measure-layout"];

// With custom arguments
[LynxTraceEvent beginSection:@"render" withName:@"draw-image" debugInfo:@{@"component": @"Image", @"size": @"large"}];
// ... your code ...
[LynxTraceEvent endSection:@"render" withName:@"draw-image"];
```

### endSection

Marks the end of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```objective-c
+ (void)endSection:(NSString *)category withName:(NSString *)name
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### Examples

```objective-c
[LynxTraceEvent beginSection:@"logic" withName:@"parse-data"];
// ... your code ...
[LynxTraceEvent endSection:@"logic" withName:@"parse-data"];
```

### instant

Marks an instant trace event.

```java
+ (void)instant:(NSString *)category withName:(NSString *)name
+ (void)instant:(NSString *)category withName:(NSString *)name debugInfo:(NSDictionary *)args
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```objective-c
[LynxTraceEvent instant:@"network" withName:@"request-started"];
// With custom arguments
[LynxTraceEvent instant:@"network" withName:@"request-finished" debugInfo:@{@"url": @"https://example.com", @"method": @"GET"}];
```

## Harmony

### beginSection

Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```javascript
static void beginSection(traceCategory: TraceCategory, name: string, args?: Record<string, string>)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

```javascript
export enum TraceCategory {
  Lynx = 'lynx',
  Vitals = 'vitals',
  Other = 'other'
}
```

##### name

The name of the trace event.

#### args (optional)

Custom arguments for the trace event.

#### Examples

```javascript
TraceEvent.beginSection(TraceCategory.Other, "measure-layout");
// ... your code ...
TraceEvent.endSection(TraceCategory.Other, "measure-layout");

// With custom arguments
const args: Record<string, string> = {
  "src": "https://example.com",
  "size": "large"
}
TraceEvent.beginSection(TraceCategory.Other, "draw-image", args);
// ... your code ...
TraceEvent.endSection(TraceCategory.Other, "draw-image");
```

### endSection

Marks the end of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```javascript
static void endSection(traceCategory: TraceCategory, name: string)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

```javascript
export enum TraceCategory {
  Lynx = 'lynx',
  Vitals = 'vitals',
  Other = 'other'
}
```

##### name

The name of the trace event.

#### Examples

```javascript
TraceEvent.beginSection(TraceCategory.Other, "parse-data");
// ... your code ...
TraceEvent.endSection(TraceCategory.Other, "parse-data");
```

### instant

Marks an instant trace event.

```javascript
static instant(traceCategory: TraceCategory, name: string, args?: Record<string, string>)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```javascript
TraceEvent.instant(TraceCategory.Other, "request-started");

// With custom arguments
const args: Record<string, string> = {
  "url": "https://example.com",
  "method": "GET"
}
TraceEvent.instant(TraceCategory.Other, "request-finished", args);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.trace-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |

**Description:** TraceEvent




---
url: /api/lynx-testing-environment/Class.LynxTestingEnv.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / LynxTestingEnv

# Class: LynxTestingEnv

A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md),
notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js.

## Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';

const lynxTestingEnv = new LynxTestingEnv();

lynxTestingEnv.switchToMainThread();
// use the main thread Element PAPI
const page = __CreatePage('0', 0);
const view = __CreateView(0);
__AppendElement(page, view);

```

## Constructors

### new LynxTestingEnv()

```ts
new LynxTestingEnv(): LynxTestingEnv
```

#### Returns

[`LynxTestingEnv`](/api/lynx-testing-environment/Class.LynxTestingEnv.md)

#### Defined in

index.d.ts:108

## Properties

### backgroundThread

```ts
backgroundThread: LynxGlobalThis;
```

The global object for the background thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';

const lynxTestingEnv = new LynxTestingEnv();

lynxTestingEnv.switchToBackgroundThread();
// use the background thread global object
globalThis.lynxCoreInject.tt.OnLifecycleEvent(...args);
```

#### Defined in

index.d.ts:88

***

### jsdom

```ts
jsdom: JSDOM;
```

#### Defined in

index.d.ts:107

***

### mainThread

```ts
mainThread: LynxGlobalThis & ElementTreeGlobals;
```

The global object for the main thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';

const lynxTestingEnv = new LynxTestingEnv();

lynxTestingEnv.switchToMainThread();
// use the main thread global object
const page = globalThis.__CreatePage('0', 0);
const view = globalThis.__CreateView(0);
globalThis.__AppendElement(page, view);
```

#### Defined in

index.d.ts:106

## Methods

### clearGlobal()

```ts
clearGlobal(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:112

***

### injectGlobals()

```ts
injectGlobals(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:109

***

### reset()

```ts
reset(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:113

***

### switchToBackgroundThread()

```ts
switchToBackgroundThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:110

***

### switchToMainThread()

```ts
switchToMainThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:111



---
url: /api/lynx-testing-environment/Function.initElementTree.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / initElementTree

# Function: initElementTree()

```ts
function initElementTree(): object
```

## Returns

`object`

### root

```ts
root: undefined | LynxElement;
```

### \_\_AddDataset()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `key`     | `string`                                                                |
| `value`   | `string`                                                                |

#### Returns

`void`

### \_\_AddEvent()

#### Parameters

| Parameter      | Type                                                                    |
| -------------- | ----------------------------------------------------------------------- |
| `e`            | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `eventType`    | `string`                                                                |
| `eventName`    | `string`                                                                |
| `eventHandler` | `string` \| `Record`\<`string`, `any`>                                  |

#### Returns

`void`

### \_\_AddInlineStyle()

#### Parameters

| Parameter | Type          |
| --------- | ------------- |
| `e`       | `HTMLElement` |
| `key`     | `number`      |
| `value`   | `string`      |

#### Returns

`void`

### \_\_AppendElement()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `parent`  | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `child`   | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_CreateElement()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `tag`                     | `string` |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateImage()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateList()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |
| `componentAtIndex`        | `any`    |
| `enqueueComponent`        | `any`    |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreatePage()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `_tag`                    | `string` |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateRawText()

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `text`    | `string` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateScrollView()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateText()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateView()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateWrapperElement()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_FirstElement()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_FlushElementTree()

#### Returns

`void`

### \_\_GetAttributeByName()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `ele`     | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `name`    | `string`                                                                |

#### Returns

`null` | `string`

### \_\_GetDataset()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`DOMStringMap`

### \_\_GetElementByUniqueId()

#### Parameters

| Parameter  | Type     |
| ---------- | -------- |
| `uniqueId` | `number` |

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_GetElementUniqueID()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`number`

### \_\_GetEvent()

#### Parameters

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `e`         | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `eventType` | `string`                                                                |
| `eventName` | `string`                                                                |

#### Returns

`undefined` | `object`

### \_\_GetTag()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `ele`     | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`string`

### \_\_InsertElementBefore()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `parent`  | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `child`   | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `ref`?    | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_RemoveElement()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `parent`  | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `child`   | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_ReplaceElement()

#### Parameters

| Parameter    | Type                                                                    |
| ------------ | ----------------------------------------------------------------------- |
| `newElement` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `oldElement` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_SetAttribute()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `key`     | `string`                                                                |
| `value`   | `any`                                                                   |

#### Returns

`void`

### \_\_SetClasses()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `cls`     | `string`                                                                |

#### Returns

`void`

### \_\_SetCSSId()

#### Parameters

| Parameter    | Type                                                                                                                                                  |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `e`          | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) \| [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)\[] |
| `id`         | `string`                                                                                                                                              |
| `entryName`? | `string`                                                                                                                                              |

#### Returns

`void`

### \_\_SetDataset()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `dataset` | `any`                                                                   |

#### Returns

`void`

### \_\_SetGestureDetector()

#### Parameters

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `e`           | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `id`          | `number`                                                                |
| `type`        | `number`                                                                |
| `config`      | `any`                                                                   |
| `relationMap` | `Record`\<`string`, `number`\[]>                                        |

#### Returns

`void`

### \_\_SetID()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `id`      | `string`                                                                |

#### Returns

`void`

### \_\_SetInlineStyles()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `styles`  | `string` \| `Record`\<`string`, `string`>                               |

#### Returns

`void`

### \_\_UpdateListCallbacks()

#### Parameters

| Parameter          | Type                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list`             | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)                                                                                                                                 |
| `componentAtIndex` | (`list`: [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md), `listID`: `number`, `cellIndex`: `number`, `operationID`: `number`, `enable_reuse_notification`: `boolean`) => `void` |
| `enqueueComponent` | (`list`: [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md), `listID`: `number`, `sign`: `number`) => `void`                                                                       |

#### Returns

`void`

### \_\_UpdateListComponents()

#### Parameters

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `_list`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `_components` | `string`\[]                                                             |

#### Returns

`void`

### clear()

#### Returns

`void`

### countElement()

#### Parameters

| Parameter                 | Type                                                                    |
| ------------------------- | ----------------------------------------------------------------------- |
| `element`                 | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `parentComponentUniqueId` | `number`                                                                |

#### Returns

`void`

### enterListItemAtIndex()

Enter a list-item element at the given index.
It will load the list-item element using the `componentAtIndex` callback.

#### Parameters

| Parameter | Type                                                                    | Description                                        |
| --------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) | The list element                                   |
| `index`   | `number`                                                                | The index of the list-item element                 |
| ...`args` | `any`\[]                                                                | The arguments used to create the list-item element |

#### Returns

`number`

The unique id of the list-item element

### leaveListItem()

Leave a list-item element.
It will mark the list-item element as unused using
the `enqueueComponent` callback, and the list-item element
will be reused in the future by other list-item elements.

#### Parameters

| Parameter | Type                                                                    | Description                            |
| --------- | ----------------------------------------------------------------------- | -------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) | The list element                       |
| `uiSign`  | `number`                                                                | The unique id of the list-item element |

#### Returns

`void`

### toJSON()

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### toTree()

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

## Defined in

lynx/ElementPAPI.d.ts:47



---
url: /api/lynx-testing-environment/Interface.LynxElement.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / LynxElement

# Interface: LynxElement

Any Lynx Element, such as `view`, `text`, `image`, etc.

[Lynx Spec Reference](/guide/spec.html?ts=1743416098203#element%E2%91%A0)

## Extends

- `HTMLElement`

## Properties

### cssId?

```ts
optional cssId: string;
```

The cssId of the element

#### Defined in

lynx/ElementPAPI.d.ts:24

***

### eventMap?

```ts
optional eventMap: object;
```

The map of events bound to the element.

#### Index Signature

\[`key`: `string`]: `any`

#### Defined in

lynx/ElementPAPI.d.ts:12

***

### firstChild

```ts
firstChild: LynxElement;
```

Returns the first child.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/firstChild)

#### Defined in

lynx/ElementPAPI.d.ts:30

***

### gesture?

```ts
optional gesture: object;
```

The gestures bound to the element.

#### Index Signature

\[`key`: `string`]: `any`

#### Defined in

lynx/ElementPAPI.d.ts:18

***

### nextSibling

```ts
nextSibling: LynxElement;
```

Returns the next sibling.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/nextSibling)

#### Defined in

lynx/ElementPAPI.d.ts:36

***

### parentNode

```ts
parentNode: LynxElement;
```

Returns the parent.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/parentNode)

#### Defined in

lynx/ElementPAPI.d.ts:42



---
url: /api/lynx-testing-environment/Interface.LynxGlobalThis.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / LynxGlobalThis

# Interface: LynxGlobalThis

The `globalThis` object of Lynx dual thread environment.

## Indexable

\[`key`: `string`]: `any`

## Properties

### globalThis

```ts
globalThis: LynxGlobalThis;
```

The globalThis object.

#### Defined in

lynx/GlobalThis.d.ts:11



---
url: /api/lynx-testing-environment/TypeAlias.ElementTree.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / ElementTree

# Type Alias: ElementTree

```ts
type ElementTree: ReturnType<typeof initElementTree>;
```

The lynx element tree

## Defined in

index.d.ts:17



---
url: /api/lynx-testing-environment/TypeAlias.ElementTreeGlobals.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / ElementTreeGlobals

# Type Alias: ElementTreeGlobals

```ts
type ElementTreeGlobals: PickUnderscoreKeys<ElementTree>;
```

The Element PAPI Types

## Defined in

index.d.ts:32



---
url: /api/lynx-testing-environment/TypeAlias.FilterUnderscoreKeys.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / FilterUnderscoreKeys

# Type Alias: FilterUnderscoreKeys\<T>

```ts
type FilterUnderscoreKeys<T>: { [K in keyof T]: K extends `__${string}` ? K : never }[keyof T];
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Defined in

index.d.ts:21



---
url: /api/lynx-testing-environment/TypeAlias.PickUnderscoreKeys.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[lynx-testing-environment](/api/lynx-testing-environment/index.md) / PickUnderscoreKeys

# Type Alias: PickUnderscoreKeys\<T>

```ts
type PickUnderscoreKeys<T>: Pick<T, FilterUnderscoreKeys<T>>;
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Defined in

index.d.ts:27



---
url: /api/lynx-testing-environment/index.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


# @lynx-js/testing-environment

`@lynx-js/testing-environment` is a pure-JavaScript implementation of the [Lynx Spec](/api/engine/element-api.md), notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js. In general, the goal of the project is to emulate enough of a subset of a Lynx environment to be useful for testing.

The Element PAPI implementation is based on jsdom, for example `__CreateElement` will return a `LynxElement`, which extends `HTMLElement` from jsdom. You can reuse the testing utilities that are commonly used for DOM testing, such as [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) (for DOM querying) and [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) (custom jest matchers for the DOM), etc.

## Usage

```js
import { LynxTestingEnv } from '@lynx-js/testing-environment';

const lynxTestingEnv = new LynxTestingEnv();
```

To use `@lynx-js/testing-environment`, you will primarily use the `LynxTestingEnv` constructor, which is a named export of the package. You will get back a `LynxTestingEnv` instance, which has a number of methods of useful properties, notably `switchToMainThread` and `switchToBackgroundThread`, which allow you to switch between the main thread and background thread.

Use the background thread API:

```js
lynxTestingEnv.switchToBackgroundThread();
// use the background thread global object
globalThis.lynxCoreInject.tt.OnLifecycleEvent(...args);
// or directly use `lynxCoreInject` since it's already injected to `globalThis`
// lynxCoreInject.tt.OnLifecycleEvent(...args);
```

Use the main thread API:

```js
lynxTestingEnv.switchToMainThread();
// use the main thread Element PAPI
const page = __CreatePage('0', 0);
const view = __CreateView(0);
__AppendElement(page, view);
```

Note that you can still access the other thread's globals without switching threads:

```js
lynxTestingEnv.switchToMainThread();
// use the `backgroundThread` global object even though we're on the main thread
lynxTestingEnv.backgroundThread.tt.OnLifecycleEvent(...args);
```

### Use in Vitest

It is recommended to configure as Vitest's [test environment](https://vitest.dev/guide/environment), for example:

```js
// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: require.resolve(
      '@lynx-js/testing-environment/env/vitest',
    ),
  },
});
```

After configuration, you can directly access the `lynxTestingEnv` object globally in the test.

If you want to use `@lynx-js/testing-environment` for unit testing in ReactLynx, you usually don't need to specify this configuration manually.

Please refer to [ReactLynx Testing Library](/react/reactlynx-testing-library.md) to inherit the configuration from `@lynx-js/react/testing-library`.

## Credits

Thanks to:

- [jsdom](https://github.com/jsdom/jsdom) for the pure-JavaScript implementation of DOM API.

A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md),
notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js.

## Classes

| Class                                                                   | Description                                                                                                                                                                                                     |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [LynxTestingEnv](/api/lynx-testing-environment/Class.LynxTestingEnv.md) | A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md), notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js. |

## Interfaces

| Interface                                                                   | Description                                              |
| --------------------------------------------------------------------------- | -------------------------------------------------------- |
| [LynxElement](/api/lynx-testing-environment/Interface.LynxElement.md)       | Any Lynx Element, such as `view`, `text`, `image`, etc.  |
| [LynxGlobalThis](/api/lynx-testing-environment/Interface.LynxGlobalThis.md) | The `globalThis` object of Lynx dual thread environment. |

## Type Aliases

| Type alias                                                                              | Description            |
| --------------------------------------------------------------------------------------- | ---------------------- |
| [ElementTree](/api/lynx-testing-environment/TypeAlias.ElementTree.md)                   | The lynx element tree  |
| [ElementTreeGlobals](/api/lynx-testing-environment/TypeAlias.ElementTreeGlobals.md)     | The Element PAPI Types |
| [FilterUnderscoreKeys](/api/lynx-testing-environment/TypeAlias.FilterUnderscoreKeys.md) | -                      |
| [PickUnderscoreKeys](/api/lynx-testing-environment/TypeAlias.PickUnderscoreKeys.md)     | -                      |

## Functions

| Function                                                                     | Description |
| ---------------------------------------------------------------------------- | ----------- |
| [initElementTree](/api/lynx-testing-environment/Function.initElementTree.md) | -           |



---
url: /api/react/Class.Component.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / Component

# Class: Component\<P, S, SS>

## Extends

- `ComponentLifecycle`\<`P`, `S`, `SS`>

## Extended by

- [`PureComponent`](/api/react/Class.PureComponent.md)

## Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `P`            | `object`     |
| `S`            | `object`     |
| `SS`           | `any`        |

## Constructors

### new Component()

```ts
new Component<P, S, SS>(props: P): Component<P, S, SS>
```

#### Parameters

| Parameter | Type |
| --------- | ---- |
| `props`   | `P`  |

#### Returns

[`Component`](/api/react/Class.Component.md)\<`P`, `S`, `SS`>

#### Inherited from

`ComponentLifecycle<P, S, SS>.constructor`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1009

### new Component()

```ts
new Component<P, S, SS>(props: P, context: any): Component<P, S, SS>
```

#### Parameters

| Parameter | Type  |
| --------- | ----- |
| `props`   | `P`   |
| `context` | `any` |

#### Returns

[`Component`](/api/react/Class.Component.md)\<`P`, `S`, `SS`>

#### Deprecated

#### See

[React Docs](https://legacy.reactjs.org/docs/legacy-context.html)

#### Inherited from

`ComponentLifecycle<P, S, SS>.constructor`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1014

## Properties

### context

```ts
context: unknown;
```

If using the new style context, re-declare this in your class to be the
`React.ContextType` of your `static contextType`.
Should be used with type annotation or static contextType.

#### Example

```ts
static contextType = MyContext
// For TS pre-3.7:
context!: React.ContextType<typeof MyContext>
// For TS 3.7 and above:
declare context: React.ContextType<typeof MyContext>
```

#### See

[React Docs](https://react.dev/reference/react/Component#context)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1007

***

### props

```ts
readonly props: Readonly<P>;
```

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1027

***

### ~~refs~~

```ts
refs: object;
```

#### Index Signature

\[`key`: `string`]: `ReactInstance`

#### Deprecated

#### See

[Legacy React Docs](https://legacy.reactjs.org/docs/refs-and-the-dom.html#legacy-api-string-refs)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1034

***

### state

```ts
state: Readonly<S>;
```

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1028

***

### contextType?

```ts
static optional contextType: Context<any>;
```

If set, `this.context` will be set at runtime to the current value of the given Context.

#### Example

```ts
type MyContext = number
const Ctx = React.createContext<MyContext>(0)

class Foo extends React.Component {
  static contextType = Ctx
  context!: React.ContextType<typeof Ctx>
  render () {
    return <>My context's value: {this.context}</>;
  }
}
```

#### See

[https://react.dev/reference/react/Component#static-contexttype](https://react.dev/reference/react/Component#static-contexttype)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:989

## Methods

### componentDidCatch()?

```ts
optional componentDidCatch(error: Error, errorInfo: ErrorInfo): void
```

Catches exceptions generated in descendant components. Unhandled exceptions will cause
the entire component tree to unmount.

#### Parameters

| Parameter   | Type        |
| ----------- | ----------- |
| `error`     | `Error`     |
| `errorInfo` | `ErrorInfo` |

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentDidCatch`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1391

***

### componentDidMount()?

```ts
optional componentDidMount(): void
```

Called immediately after a component is mounted. Setting state here will trigger re-rendering.

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentDidMount`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1370

***

### componentDidUpdate()?

```ts
optional componentDidUpdate(
   prevProps: Readonly<P>, 
   prevState: Readonly<S>, 
   snapshot?: SS): void
```

Called immediately after updating occurs. Not called for the initial render.

The snapshot is only present if [getSnapshotBeforeUpdate](/api/react/Class.Component.md#getsnapshotbeforeupdate) is present and returns non-null.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |
| `snapshot`? | `SS`             |

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentDidUpdate`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1433

***

### ~~componentWillMount()?~~

```ts
optional componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.componentWillMount`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1449

***

### ~~componentWillReceiveProps()?~~

```ts
optional componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.componentWillReceiveProps`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1480

***

### componentWillUnmount()?

```ts
optional componentWillUnmount(): void
```

Called immediately before a component is destroyed. Perform any necessary cleanup in this method, such as
cancelled network requests, or cleaning up any DOM elements created in `componentDidMount`.

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentWillUnmount`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1386

***

### ~~componentWillUpdate()?~~

```ts
optional componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.componentWillUpdate`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1512

***

### forceUpdate()

```ts
forceUpdate(callback?: () => void): void
```

#### Parameters

| Parameter   | Type         |
| ----------- | ------------ |
| `callback`? | () => `void` |

#### Returns

`void`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1024

***

### getSnapshotBeforeUpdate()?

```ts
optional getSnapshotBeforeUpdate(prevProps: Readonly<P>, prevState: Readonly<S>): SS
```

Runs before React applies the result of [render](/api/react/Class.Component.md#render) to the document, and
returns an object to be given to [componentDidUpdate](/api/react/Class.Component.md#componentdidupdate). Useful for saving
things such as scroll position before [render](/api/react/Class.Component.md#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated
lifecycle events from running.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |

#### Returns

`SS`

#### Inherited from

`ComponentLifecycle.getSnapshotBeforeUpdate`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1427

***

### render()

```ts
render(): ReactNode
```

#### Returns

`ReactNode`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1025

***

### setState()

```ts
setState<K>(state: S | (prevState: Readonly<S>, props: Readonly<P>) => S | Pick<S, K> | Pick<S, K>, callback?: () => void): void
```

#### Type Parameters

| Type Parameter                                 |
| ---------------------------------------------- |
| `K` _extends_ `string` \| `number` \| `symbol` |

#### Parameters

| Parameter   | Type                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `state`     | `S` \| (`prevState`: `Readonly`\<`S`>, `props`: `Readonly`\<`P`>) => `S` \| `Pick`\<`S`, `K`> \| `Pick`\<`S`, `K`> |
| `callback`? | () => `void`                                                                                                       |

#### Returns

`void`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1019

***

### shouldComponentUpdate()?

```ts
optional shouldComponentUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): boolean
```

Called to determine whether the change in props and state should trigger a re-render.

`Component` always returns true.
`PureComponent` implements a shallow comparison on props and state and returns true if any
props or states have changed.

If false is returned, [Component.render](/api/react/Class.Component.md#render), `componentWillUpdate`
and `componentDidUpdate` will not be called.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`boolean`

#### Inherited from

`ComponentLifecycle.shouldComponentUpdate`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1381

***

### ~~UNSAFE\_componentWillMount()?~~

```ts
optional UNSAFE_componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.UNSAFE_componentWillMount`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1464

***

### ~~UNSAFE\_componentWillReceiveProps()?~~

```ts
optional UNSAFE_componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.UNSAFE_componentWillReceiveProps`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1498

***

### ~~UNSAFE\_componentWillUpdate()?~~

```ts
optional UNSAFE_componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.UNSAFE_componentWillUpdate`

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1528



---
url: /api/react/Class.MainThreadRef.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / MainThreadRef

# Class: MainThreadRef\<T>

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

## Extends

- `WorkletRef`\<`T`>

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Constructors

### new MainThreadRef()

```ts
new MainThreadRef<T>(initValue: T): MainThreadRef<T>
```

#### Parameters

| Parameter   | Type |
| ----------- | ---- |
| `initValue` | `T`  |

#### Returns

[`MainThreadRef`](/api/react/Class.MainThreadRef.md)\<`T`>

#### Overrides

`WorkletRef<T>.constructor`

#### Defined in

@lynx-js/react/runtime/lib/worklet/ref/workletRef.d.ts:15

## Accessors

### current

#### Get Signature

```ts
get current(): T
```

##### Returns

`T`

#### Set Signature

```ts
set current(_: T): void
```

##### Parameters

| Parameter | Type |
| --------- | ---- |
| `_`       | `T`  |

##### Returns

`void`

#### Inherited from

`WorkletRef.current`

#### Defined in

@lynx-js/react/runtime/lib/worklet/ref/workletRef.d.ts:4



---
url: /api/react/Class.PureComponent.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / PureComponent

# Class: PureComponent\<P, S, SS>

## Extends

- [`Component`](/api/react/Class.Component.md)\<`P`, `S`, `SS`>

## Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `P`            | `object`     |
| `S`            | `object`     |
| `SS`           | `any`        |

## Constructors

### new PureComponent()

```ts
new PureComponent<P, S, SS>(props: P): PureComponent<P, S, SS>
```

#### Parameters

| Parameter | Type |
| --------- | ---- |
| `props`   | `P`  |

#### Returns

[`PureComponent`](/api/react/Class.PureComponent.md)\<`P`, `S`, `SS`>

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`constructor`](/api/react/Class.Component.md#constructors)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1009

### new PureComponent()

```ts
new PureComponent<P, S, SS>(props: P, context: any): PureComponent<P, S, SS>
```

#### Parameters

| Parameter | Type  |
| --------- | ----- |
| `props`   | `P`   |
| `context` | `any` |

#### Returns

[`PureComponent`](/api/react/Class.PureComponent.md)\<`P`, `S`, `SS`>

#### Deprecated

#### See

[React Docs](https://legacy.reactjs.org/docs/legacy-context.html)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`constructor`](/api/react/Class.Component.md#constructors)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1014

## Properties

### context

```ts
context: unknown;
```

If using the new style context, re-declare this in your class to be the
`React.ContextType` of your `static contextType`.
Should be used with type annotation or static contextType.

#### Example

```ts
static contextType = MyContext
// For TS pre-3.7:
context!: React.ContextType<typeof MyContext>
// For TS 3.7 and above:
declare context: React.ContextType<typeof MyContext>
```

#### See

[React Docs](https://react.dev/reference/react/Component#context)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`context`](/api/react/Class.Component.md#context)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1007

***

### props

```ts
readonly props: Readonly<P>;
```

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`props`](/api/react/Class.Component.md#props)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1027

***

### ~~refs~~

```ts
refs: object;
```

#### Index Signature

\[`key`: `string`]: `ReactInstance`

#### Deprecated

#### See

[Legacy React Docs](https://legacy.reactjs.org/docs/refs-and-the-dom.html#legacy-api-string-refs)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`refs`](/api/react/Class.Component.md#refs)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1034

***

### state

```ts
state: Readonly<S>;
```

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`state`](/api/react/Class.Component.md#state)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1028

***

### contextType?

```ts
static optional contextType: Context<any>;
```

If set, `this.context` will be set at runtime to the current value of the given Context.

#### Example

```ts
type MyContext = number
const Ctx = React.createContext<MyContext>(0)

class Foo extends React.Component {
  static contextType = Ctx
  context!: React.ContextType<typeof Ctx>
  render () {
    return <>My context's value: {this.context}</>;
  }
}
```

#### See

[https://react.dev/reference/react/Component#static-contexttype](https://react.dev/reference/react/Component#static-contexttype)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`contextType`](/api/react/Class.Component.md#contexttype)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:989

## Methods

### componentDidCatch()?

```ts
optional componentDidCatch(error: Error, errorInfo: ErrorInfo): void
```

Catches exceptions generated in descendant components. Unhandled exceptions will cause
the entire component tree to unmount.

#### Parameters

| Parameter   | Type        |
| ----------- | ----------- |
| `error`     | `Error`     |
| `errorInfo` | `ErrorInfo` |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentDidCatch`](/api/react/Class.Component.md#componentdidcatch)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1391

***

### componentDidMount()?

```ts
optional componentDidMount(): void
```

Called immediately after a component is mounted. Setting state here will trigger re-rendering.

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentDidMount`](/api/react/Class.Component.md#componentdidmount)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1370

***

### componentDidUpdate()?

```ts
optional componentDidUpdate(
   prevProps: Readonly<P>, 
   prevState: Readonly<S>, 
   snapshot?: SS): void
```

Called immediately after updating occurs. Not called for the initial render.

The snapshot is only present if [getSnapshotBeforeUpdate](/api/react/Class.PureComponent.md#getsnapshotbeforeupdate) is present and returns non-null.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |
| `snapshot`? | `SS`             |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentDidUpdate`](/api/react/Class.Component.md#componentdidupdate)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1433

***

### ~~componentWillMount()?~~

```ts
optional componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillMount`](/api/react/Class.Component.md#componentwillmount)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1449

***

### ~~componentWillReceiveProps()?~~

```ts
optional componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillReceiveProps`](/api/react/Class.Component.md#componentwillreceiveprops)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1480

***

### componentWillUnmount()?

```ts
optional componentWillUnmount(): void
```

Called immediately before a component is destroyed. Perform any necessary cleanup in this method, such as
cancelled network requests, or cleaning up any DOM elements created in `componentDidMount`.

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillUnmount`](/api/react/Class.Component.md#componentwillunmount)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1386

***

### ~~componentWillUpdate()?~~

```ts
optional componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillUpdate`](/api/react/Class.Component.md#componentwillupdate)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1512

***

### forceUpdate()

```ts
forceUpdate(callback?: () => void): void
```

#### Parameters

| Parameter   | Type         |
| ----------- | ------------ |
| `callback`? | () => `void` |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`forceUpdate`](/api/react/Class.Component.md#forceupdate)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1024

***

### getSnapshotBeforeUpdate()?

```ts
optional getSnapshotBeforeUpdate(prevProps: Readonly<P>, prevState: Readonly<S>): SS
```

Runs before React applies the result of [render](/api/react/Class.Component.md#render) to the document, and
returns an object to be given to [componentDidUpdate](/api/react/Class.PureComponent.md#componentdidupdate). Useful for saving
things such as scroll position before [render](/api/react/Class.Component.md#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated
lifecycle events from running.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |

#### Returns

`SS`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`getSnapshotBeforeUpdate`](/api/react/Class.Component.md#getsnapshotbeforeupdate)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1427

***

### render()

```ts
render(): ReactNode
```

#### Returns

`ReactNode`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`render`](/api/react/Class.Component.md#render)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1025

***

### setState()

```ts
setState<K>(state: S | (prevState: Readonly<S>, props: Readonly<P>) => S | Pick<S, K> | Pick<S, K>, callback?: () => void): void
```

#### Type Parameters

| Type Parameter                                 |
| ---------------------------------------------- |
| `K` _extends_ `string` \| `number` \| `symbol` |

#### Parameters

| Parameter   | Type                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `state`     | `S` \| (`prevState`: `Readonly`\<`S`>, `props`: `Readonly`\<`P`>) => `S` \| `Pick`\<`S`, `K`> \| `Pick`\<`S`, `K`> |
| `callback`? | () => `void`                                                                                                       |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`setState`](/api/react/Class.Component.md#setstate)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1019

***

### shouldComponentUpdate()?

```ts
optional shouldComponentUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): boolean
```

Called to determine whether the change in props and state should trigger a re-render.

`Component` always returns true.
`PureComponent` implements a shallow comparison on props and state and returns true if any
props or states have changed.

If false is returned, [Component.render](/api/react/Class.Component.md#render), `componentWillUpdate`
and `componentDidUpdate` will not be called.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`boolean`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`shouldComponentUpdate`](/api/react/Class.Component.md#shouldcomponentupdate)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1381

***

### ~~UNSAFE\_componentWillMount()?~~

```ts
optional UNSAFE_componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`UNSAFE_componentWillMount`](/api/react/Class.Component.md#unsafe_componentwillmount)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1464

***

### ~~UNSAFE\_componentWillReceiveProps()?~~

```ts
optional UNSAFE_componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`UNSAFE_componentWillReceiveProps`](/api/react/Class.Component.md#unsafe_componentwillreceiveprops)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1498

***

### ~~UNSAFE\_componentWillUpdate()?~~

```ts
optional UNSAFE_componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`UNSAFE_componentWillUpdate`](/api/react/Class.Component.md#unsafe_componentwillupdate)

#### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1528



---
url: /api/react/Document.built-in-macros.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / built-in-macros

# Built-in Macros

The `@lynx-js/react` package processes built-in macro definitions such as `__BACKGROUND__` and `__MAIN_THREAD__`. During compilation, code blocks with `false` conditions are automatically removed.

## `__BACKGROUND__`

- Type: `boolean`
- Purpose: Controls code execution in background thread environment. Used to determine which code segments should be preserved in background thread code after compilation.

### Usage Examples

#### In Function Components

Here's an example using the `App` component:

```tsx
import { noop } from 'lodash-es';
import { useEffect } from '@lynx-js/react';

function App() {
  const showToast = __BACKGROUND__
    ? () => {
        bridge.call('showToast', {
          message: t('toast'),
          icon: 'success',
        });
      }
    : noop;

  useEffect(showToast, []);
  return <view />;
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = () => {
    bridge.call('showToast', {
      message: t('toast'),
      icon: 'success',
    });
  };
  useEffect(showToast, []);
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = noop_default;

  useEffect();
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

#### In Class Components

Here's an example using the `Conversations` component:

```tsx
import { AppLoggerFactory } from '../utils/appLoggerFactory';

class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    if (__BACKGROUND__) {
      this.appLogger = AppLoggerFactory();
    }
  }
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    this.appLogger = AppLoggerFactory();
  }
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
  }
}
```

## `__MAIN_THREAD__`

- Type: `boolean`
- Purpose: Controls code execution in main thread environment. Used to determine which code segments should be preserved in main thread code during compilation.

### Usage Examples

#### In Function Components

Here's an example using the `App` component:

```tsx
import { noop } from 'lodash-es';
import { useEffect } from '@lynx-js/react';

function App() {
  const showToast = !__MAIN_THREAD__
    ? () => {
        bridge.call('showToast', {
          message: t('toast'),
          icon: 'success',
        });
      }
    : noop;

  useEffect(showToast, []);
  return <view />;
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = () => {
    bridge.call('showToast', {
      message: t('toast'),
      icon: 'success',
    });
  };
  useEffect(showToast, []);
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = noop_default;

  useEffect();
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

#### In Class Components

Here's an example using the `Conversations` component:

```tsx
import { AppLoggerFactory } from '../utils/appLoggerFactory';

class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    if (!__MAIN_THREAD__) {
      this.appLogger = AppLoggerFactory();
    }
  }
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    this.appLogger = AppLoggerFactory();
  }
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
  }
}
```



---
url: /api/react/Document.directives.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / directives

# Directives

## `'background only'`

The `'background only'` directive allows you to mark functions that will only be executed on the background thread. In other threads, the function body of the marked function will be removed.

To mark a function as background only, simply add the `'background only'` directive at the first line of the function body:

```ts
function bgOnlyAction(pureCallback) {
  'background only';
  lynx.getJSModule('GlobalEventEmitter').addListener('eventName', pureCallback);
}
```

In the main thread portion of the generated output, this function will be replaced as follows:

```ts
function bgOnlyAction(pureCallback) {}
```

Typically, code with side effects should only be executed in the background thread, such as event listeners, JSB calls, etc. Marking such functions as `'background only'` can significantly reduce the bundle size.

One way to use `'background only'` is in conjunction with custom hooks. For example, `useFirstRender` is a user-defined hook used to execute some logic when a component is first rendered. We want to use it to listen for events. The event listening logic should not and cannot be executed on the main thread. In this case, we can use the `'background only'` directive to mark this function, removing the event listening logic from the main thread.

```ts
import {useFirstRender} from './useFirstRender';

function bgOnlyAction(pureCallback) {
  'background only';
  lynx.getJSModule('GlobalEventEmitter').addListener('eventName', pureCallback);
}

function Foo({ prop } ){
  const ref = useRef(null);
  useFirstRender(() => {
    bgOnlyAction(() => {
      // ...
    });
  });
  return <view>;
}
```

It is not only the code marked as `'background only'` that will be removed in other threads; ReactLynx will by default remove certain parts of the code, including the parameters of `useEffect`, `useLayoutEffect`, and some event handlers, among others. For these parts, you do not need to mark the corresponding functions as `'background only'`. For more details, refer to [Dual Runtime Code Splitting](/react/thinking-in-reactlynx.md).

## `'main thread'`

The `'main thread'` directive allows you to mark main thread functions. Main thread functions are part of the [Main Thread Script](/react/main-thread-script.md) system and can only be executed on the main thread. They are primarily used for smooth animations and gesture handling.

To convert a background thread function into a main thread function, simply add the `'main thread'` directive at the first line of the function:

```tsx {7}
import {MainThread} from "@lynx-js/types";

export default function App() {
  const red = 'red';

  function handleTap(event: MainThread.TouchEvent) {
    'main thread';
    event.currentTarget.setStyleProperty('background-color', red);
  }

  return (
    <view main-thread:bindtap={handleTap}>
      <text>Hello World!</text>
    </view>
  );
}
```

A main thread function will automatically capture external variables from the background thread when defined, such as `red` in the example above.

When using a main thread function as an event handler, the main thread function accepts an `event` parameter that contains basic information about the event. The `event.target` and `event.currentTarget` parameters differ from those in regular event handlers; they are [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md) objects. This object allows you to conveniently synchronize the retrieval and setting of node properties, such as using [`setStyleProperty()`] in the example.

Some important notes:

- Main thread functions can and must only run on the main thread. Main thread functions can call each other.
- Captured variables need to be passed between threads using `JSON.stringify()`, so they must be serializable to JSON.
- Main thread functions can only execute after TTI (Time to Interactive). This means they cannot execute during the initial screen load.
- Main thread functions do not support nested definitions.
- The constructor, getter, and setter of class components do not support being specified as main thread functions.
- You cannot modify variables captured from the external scope within a main thread function.

[`setStyleProperty()`]: /api/lynx-api/main-thread/main-thread-element.md#elementsetstyleproperty



---
url: /api/react/Document.global-events.md
---

[@lynx-js/react](/api/react/index.md) / global-events

# Global Events

ReactLynx provides a series of global events that allow developers to listen and respond to application-level state changes. You can easily subscribe to these events in your components using the [`useLynxGlobalEventListener`](/api/react/Function.useLynxGlobalEventListener.md) hook.

## onGlobalPropsChanged

The `onGlobalPropsChanged` event is triggered when the [`lynx.__globalProps`](/api/lynx-api/lynx/lynx-global-props.md) object changes, automatically re-rendering the entire page afterward.
This is useful for components that need to react to global configuration changes, such as themes, languages, etc.

As a result, `onGlobalPropsChanged` is mainly used for handling side effects that are **not directly related to UI rendering**, such as data fetching.

The callback function for this event does not receive any arguments; you can read the latest state directly from [`lynx.__globalProps`](/api/lynx-api/lynx/lynx-global-props.md).

```tsx
import { useLynxGlobalEventListener } from '@lynx-js/react';

function App() {
  useLynxGlobalEventListener('onGlobalPropsChanged', () => {
    console.log('Global props changed:', lynx.__globalProps);
    // You can perform data fetching or other operations here
  });

  return <view>...</view>;
}
```

## onDataChanged

The `onDataChanged` event is triggered when [`initData`](/api/react/Function.useInitData.md) is updated by the client.

[`useInitData`](/api/react/Function.useInitData.md) is a responsive hook that automatically triggers a component re-render when `initData` changes.
The `onDataChanged` event is primarily used to handle side effects that are **not directly related to UI rendering**, such as logging, data analytics, or executing other imperative operations.

```tsx
import { useLynxGlobalEventListener } from '@lynx-js/react';

function DataChangeLogger() {
  useLynxGlobalEventListener('onDataChanged', (data) => {
    console.log('initData changed:', data);
    // You can perform data reporting or other operations here
  });

  return <view>...</view>;
}
```



---
url: /api/react/Function.Fragment.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / Fragment

# Function: Fragment()

```ts
function Fragment(props: object): ReactElement<any, string | JSXElementConstructor<any>>
```

Lets you group elements without a wrapper node.

## Parameters

| Parameter         | Type        |
| ----------------- | ----------- |
| `props`           | `object`    |
| `props.children`? | `ReactNode` |

## Returns

`ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## See

[React Docs](https://react.dev/reference/react/Fragment)

## Examples

```tsx
import { Fragment } from 'react';

<Fragment>
  <td>Hello</td>
  <td>World</td>
</Fragment>
```

```tsx
// Using the <></> shorthand syntax:

<>
  <td>Hello</td>
  <td>World</td>
</>
```

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:823



---
url: /api/react/Function.InitDataConsumer.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / InitDataConsumer

# Function: InitDataConsumer()

```ts
function InitDataConsumer(props: ConsumerProps<InitData>): ReactElement<any, string | JSXElementConstructor<any>>
```

The [Consumer](https://react.dev/reference/react/createContext#consumer) Component that provide `initData`.
This should be used with [InitDataProvider](/api/react/Function.InitDataProvider.md)

## Parameters

| Parameter | Type                                                             |
| --------- | ---------------------------------------------------------------- |
| `props`   | `ConsumerProps`\<[`InitData`](/api/react/Interface.InitData.md)> |

## Returns

`ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:106



---
url: /api/react/Function.InitDataProvider.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / InitDataProvider

# Function: InitDataProvider()

```ts
function InitDataProvider(props: object, deprecatedLegacyContext?: any): ReactElement<any, any>
```

The [Provider](https://react.dev/reference/react/createContext#provider) Component that provide `initData`,
you must wrap your JSX inside it

## Parameters

| Parameter                  | Type        | Description                                                                                                                       |
| -------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `props`                    | `object`    | -                                                                                                                                 |
| `props.children`?          | `ReactNode` | -                                                                                                                                 |
| `deprecatedLegacyContext`? | `any`       | **Deprecated** **See** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |

## Returns

`ReactElement`\<`any`, `any`>

## Example

```ts
import { root } from "@lynx-js/react"

function App() {
  return (
    <InitDataConsumer children={(initData) => <view>...</view>}/>
  )
}

root.render(
  <InitDataProvider>
     <App/>
  </InitDataProvider>
);

```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:97



---
url: /api/react/Function.Suspense.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / Suspense

# Function: Suspense()

```ts
function Suspense(props: SuspenseProps): ReactElement<any, string | JSXElementConstructor<any>>
```

Lets you display a fallback until its children have finished loading.

## Parameters

| Parameter | Type            |
| --------- | --------------- |
| `props`   | `SuspenseProps` |

## Returns

`ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## See

[React Docs](https://react.dev/reference/react/Suspense)

## Example

```tsx
import { Suspense } from 'react';

<Suspense fallback={<Loading />}>
  <ProfileDetails />
</Suspense>
```

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:875



---
url: /api/react/Function.cloneElement.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / cloneElement

# Function: cloneElement()

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: DetailedReactHTMLElement<P, T>, 
   props?: P, ...
children?: ReactNode[]): DetailedReactHTMLElement<P, T>
```

### Type Parameters

| Type Parameter                            |
| ----------------------------------------- |
| `P` _extends_ `HTMLAttributes`\<`T`, `P`> |
| `T` _extends_ `HTMLElement`\<`T`>         |

### Parameters

| Parameter      | Type                                  |
| -------------- | ------------------------------------- |
| `element`      | `DetailedReactHTMLElement`\<`P`, `T`> |
| `props`?       | `P`                                   |
| ...`children`? | `ReactNode`\[]                        |

### Returns

`DetailedReactHTMLElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:563

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: ReactHTMLElement<T>, 
   props?: P, ...
children?: ReactNode[]): ReactHTMLElement<T>
```

### Type Parameters

| Type Parameter                            |
| ----------------------------------------- |
| `P` _extends_ `HTMLAttributes`\<`T`, `P`> |
| `T` _extends_ `HTMLElement`\<`T`>         |

### Parameters

| Parameter      | Type                     |
| -------------- | ------------------------ |
| `element`      | `ReactHTMLElement`\<`T`> |
| `props`?       | `P`                      |
| ...`children`? | `ReactNode`\[]           |

### Returns

`ReactHTMLElement`\<`T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:569

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: ReactSVGElement, 
   props?: P, ...
   children?: ReactNode[]): ReactSVGElement
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `SVGAttributes`\<`T`, `P`> |
| `T` _extends_ `SVGElement`\<`T`>         |

### Parameters

| Parameter      | Type              |
| -------------- | ----------------- |
| `element`      | `ReactSVGElement` |
| `props`?       | `P`               |
| ...`children`? | `ReactNode`\[]    |

### Returns

`ReactSVGElement`

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:575

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: DOMElement<P, T>, 
   props?: DOMAttributes<T> & P, ...
children?: ReactNode[]): DOMElement<P, T>
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `DOMAttributes`\<`T`, `P`> |
| `T` _extends_ `Element`\<`T`>            |

### Parameters

| Parameter      | Type                        |
| -------------- | --------------------------- |
| `element`      | `DOMElement`\<`P`, `T`>     |
| `props`?       | `DOMAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]              |

### Returns

`DOMElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:581

## cloneElement(element, props, children)

```ts
function cloneElement<P>(
   element: FunctionComponentElement<P>, 
   props?: Partial<P> & Attributes, ...
children?: ReactNode[]): FunctionComponentElement<P>
```

### Type Parameters

| Type Parameter |
| -------------- |
| `P`            |

### Parameters

| Parameter      | Type                             |
| -------------- | -------------------------------- |
| `element`      | `FunctionComponentElement`\<`P`> |
| `props`?       | `Partial`\<`P`> & `Attributes`   |
| ...`children`? | `ReactNode`\[]                   |

### Returns

`FunctionComponentElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:588

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: CElement<P, T>, 
   props?: Partial<P> & ClassAttributes<T>, ...
children?: ReactNode[]): CElement<P, T>
```

### Type Parameters

| Type Parameter                                                                      |
| ----------------------------------------------------------------------------------- |
| `P`                                                                                 |
| `T` _extends_ [`Component`](/api/react/Class.Component.md)\<`P`, `any`, `any`, `T`> |

### Parameters

| Parameter      | Type                                      |
| -------------- | ----------------------------------------- |
| `element`      | `CElement`\<`P`, `T`>                     |
| `props`?       | `Partial`\<`P`> & `ClassAttributes`\<`T`> |
| ...`children`? | `ReactNode`\[]                            |

### Returns

`CElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:593

## cloneElement(element, props, children)

```ts
function cloneElement<P>(
   element: ReactElement<P, string | JSXElementConstructor<any>>, 
   props?: Partial<P> & Attributes, ...
children?: ReactNode[]): ReactElement<P>
```

### Type Parameters

| Type Parameter |
| -------------- |
| `P`            |

### Parameters

| Parameter      | Type                                                              |
| -------------- | ----------------------------------------------------------------- |
| `element`      | `ReactElement`\<`P`, `string` \| `JSXElementConstructor`\<`any`>> |
| `props`?       | `Partial`\<`P`> & `Attributes`                                    |
| ...`children`? | `ReactNode`\[]                                                    |

### Returns

`ReactElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:598



---
url: /api/react/Function.createContext.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / createContext

# Function: createContext()

```ts
function createContext<T>(defaultValue: T): Context<T>
```

Lets you create a Context that components can provide or read.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter      | Type | Description                                                                                                                                                               |
| -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultValue` | `T`  | The value you want the context to have when there is no matching Provider in the tree above the component reading the context. This is meant as a "last resort" fallback. |

## Returns

`Context`\<`T`>

## See

- [React Docs](https://react.dev/reference/react/createContext#reference)
- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/context/)

## Example

```tsx
import { createContext } from 'react';

const ThemeContext = createContext('light');
```

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:775



---
url: /api/react/Function.createElement.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / createElement

# Function: createElement()

## createElement(type, props, children)

```ts
function createElement(
   type: "input", 
   props?: InputHTMLAttributes<HTMLInputElement> & ClassAttributes<HTMLInputElement>, ...
children?: ReactNode[]): DetailedReactHTMLElement<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>
```

### Parameters

| Parameter      | Type                                                                                |
| -------------- | ----------------------------------------------------------------------------------- |
| `type`         | `"input"`                                                                           |
| `props`?       | `InputHTMLAttributes`\<`HTMLInputElement`> & `ClassAttributes`\<`HTMLInputElement`> |
| ...`children`? | `ReactNode`\[]                                                                      |

### Returns

`DetailedReactHTMLElement`\<`InputHTMLAttributes`\<`HTMLInputElement`>, `HTMLInputElement`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:522

## createElement(type, props, children)

```ts
function createElement<P, T>(
   type: keyof ReactHTML, 
   props?: ClassAttributes<T> & P, ...
children?: ReactNode[]): DetailedReactHTMLElement<P, T>
```

### Type Parameters

| Type Parameter                            |
| ----------------------------------------- |
| `P` _extends_ `HTMLAttributes`\<`T`, `P`> |
| `T` _extends_ `HTMLElement`\<`T`>         |

### Parameters

| Parameter      | Type                          |
| -------------- | ----------------------------- |
| `type`         | keyof `ReactHTML`             |
| `props`?       | `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                |

### Returns

`DetailedReactHTMLElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:527

## createElement(type, props, children)

```ts
function createElement<P, T>(
   type: keyof ReactSVG, 
   props?: ClassAttributes<T> & P, ...
   children?: ReactNode[]): ReactSVGElement
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `SVGAttributes`\<`T`, `P`> |
| `T` _extends_ `SVGElement`\<`T`>         |

### Parameters

| Parameter      | Type                          |
| -------------- | ----------------------------- |
| `type`         | keyof `ReactSVG`              |
| `props`?       | `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                |

### Returns

`ReactSVGElement`

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:532

## createElement(type, props, children)

```ts
function createElement<P, T>(
   type: string, 
   props?: ClassAttributes<T> & P, ...
children?: ReactNode[]): DOMElement<P, T>
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `DOMAttributes`\<`T`, `P`> |
| `T` _extends_ `Element`\<`T`>            |

### Parameters

| Parameter      | Type                          |
| -------------- | ----------------------------- |
| `type`         | `string`                      |
| `props`?       | `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                |

### Returns

`DOMElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:537

## createElement(type, props, children)

```ts
function createElement<P>(
   type: FunctionComponent<P>, 
   props?: Attributes & P, ...
children?: ReactNode[]): FunctionComponentElement<P>
```

### Type Parameters

| Type Parameter         |
| ---------------------- |
| `P` _extends_ `object` |

### Parameters

| Parameter      | Type                      |
| -------------- | ------------------------- |
| `type`         | `FunctionComponent`\<`P`> |
| `props`?       | `Attributes` & `P`        |
| ...`children`? | `ReactNode`\[]            |

### Returns

`FunctionComponentElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:545

## createElement(type, props, children)

```ts
function createElement<P, T, C>(
   type: ClassType<P, T, C>, 
   props?: ClassAttributes<T> & P, ...
children?: ReactNode[]): CElement<P, T>
```

### Type Parameters

| Type Parameter                                                                      |
| ----------------------------------------------------------------------------------- |
| `P` _extends_ `object`                                                              |
| `T` _extends_ [`Component`](/api/react/Class.Component.md)\<`P`, `any`, `any`, `T`> |
| `C` _extends_ `ComponentClass`\<`P`, `any`, `C`>                                    |

### Parameters

| Parameter      | Type                          |
| -------------- | ----------------------------- |
| `type`         | `ClassType`\<`P`, `T`, `C`>   |
| `props`?       | `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                |

### Returns

`CElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:550

## createElement(type, props, children)

```ts
function createElement<P>(
   type: string | FunctionComponent<P> | ComponentClass<P, any>, 
   props?: Attributes & P, ...
children?: ReactNode[]): ReactElement<P>
```

### Type Parameters

| Type Parameter         |
| ---------------------- |
| `P` _extends_ `object` |

### Parameters

| Parameter      | Type                                                                   |
| -------------- | ---------------------------------------------------------------------- |
| `type`         | `string` \| `FunctionComponent`\<`P`> \| `ComponentClass`\<`P`, `any`> |
| `props`?       | `Attributes` & `P`                                                     |
| ...`children`? | `ReactNode`\[]                                                         |

### Returns

`ReactElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:555



---
url: /api/react/Function.createRef.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / createRef

# Function: createRef()

```ts
function createRef<T>(): RefObject<T>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Returns

`RefObject`\<`T`>

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1562



---
url: /api/react/Function.createRoot.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[react](/api/react/index.md) / createRoot

# Function: ~~createRoot()~~

```ts
function createRoot(): Root
```

The default and only root of ReactLynx for you to render JSX

## Returns

[`Root`](/api/react/Interface.Root.md)

Always return [root](/api/react/Variable.root.md).

## Deprecated

use [root](/api/react/Variable.root.md) instead

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:78



---
url: /api/react/Function.forwardRef.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / forwardRef

# Function: forwardRef()

```ts
function forwardRef<T, P>(render: ForwardRefRenderFunction<T, PropsWithoutRef<P>>): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>
```

Lets your component expose a DOM node to a parent component
using a ref.

## Type Parameters

| Type Parameter | Default type | Description                              |
| -------------- | ------------ | ---------------------------------------- |
| `T`            | -            | The type of the DOM node.                |
| `P`            | `object`     | The props the component accepts, if any. |

## Parameters

| Parameter | Type                                                      | Description                       |
| --------- | --------------------------------------------------------- | --------------------------------- |
| `render`  | `ForwardRefRenderFunction`\<`T`, `PropsWithoutRef`\<`P`>> | See the ForwardRefRenderFunction. |

## Returns

`ForwardRefExoticComponent`\<`PropsWithoutRef`\<`P`> & `RefAttributes`\<`T`>>

## See

- [React Docs](https://react.dev/reference/react/forwardRef)
- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/forward_and_create_ref/)

## Example

```tsx
interface Props {
  children?: ReactNode;
  type: "submit" | "button";
}

export const FancyButton = forwardRef<HTMLButtonElement, Props>((props, ref) => (
  <button ref={ref} className="MyClassName" type={props.type}>
    {props.children}
  </button>
));
```

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1606



---
url: /api/react/Function.isValidElement.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / isValidElement

# Function: isValidElement()

```ts
function isValidElement<P>(object: object): object is ReactElement<P, string | JSXElementConstructor<any>>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `P`            |

## Parameters

| Parameter | Type     |
| --------- | -------- |
| `object`  | `object` |

## Returns

object is ReactElement\<P, string | JSXElementConstructor\<any>>

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:781



---
url: /api/react/Function.lazy.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / lazy

# Function: lazy()

```ts
function lazy<T>(load: () => Promise<object>): LazyExoticComponent<T>
```

Lets you defer loading a component’s code until it is rendered for the first time.

## Type Parameters

| Type Parameter                        |
| ------------------------------------- |
| `T` _extends_ `ComponentType`\<`any`> |

## Parameters

| Parameter | Type                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `load`    | () => `Promise`\<`object`> | A function that returns a `Promise` or another thenable (a `Promise`-like object with a then method). React will not call `load` until the first time you attempt to render the returned component. After React first calls load, it will wait for it to resolve, and then render the resolved value’s `.default` as a React component. Both the returned `Promise` and the `Promise`’s resolved value will be cached, so React will not call load more than once. If the `Promise` rejects, React will throw the rejection reason for the nearest Error Boundary to handle. |

## Returns

`LazyExoticComponent`\<`T`>

## See

[React Docs](https://react.dev/reference/react/lazy)

## Example

```tsx
import { lazy } from 'react';

const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));
```

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1802



---
url: /api/react/Function.memo.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / memo

# Function: memo()

## memo(Component, propsAreEqual)

```ts
function memo<P>(Component: FunctionComponent<P>, propsAreEqual?: (prevProps: Readonly<P>, nextProps: Readonly<P>) => boolean): NamedExoticComponent<P>
```

Lets you skip re-rendering a component when its props are unchanged.

### Type Parameters

| Type Parameter         |
| ---------------------- |
| `P` _extends_ `object` |

### Parameters

| Parameter        | Type                                                                        | Description                                                          |
| ---------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `Component`      | `FunctionComponent`\<`P`>                                                   | The component to memoize.                                            |
| `propsAreEqual`? | (`prevProps`: `Readonly`\<`P`>, `nextProps`: `Readonly`\<`P`>) => `boolean` | A function that will be used to determine if the props have changed. |

### Returns

`NamedExoticComponent`\<`P`>

### See

[React Docs](https://react.dev/reference/react/memo)

### Example

```tsx
import { memo } from 'react';

const SomeComponent = memo(function SomeComponent(props: { foo: string }) {
  // ...
});
```

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1767

## memo(Component, propsAreEqual)

```ts
function memo<T>(Component: T, propsAreEqual?: (prevProps: Readonly<ComponentProps<T>>, nextProps: Readonly<ComponentProps<T>>) => boolean): MemoExoticComponent<T>
```

### Type Parameters

| Type Parameter                        |
| ------------------------------------- |
| `T` _extends_ `ComponentType`\<`any`> |

### Parameters

| Parameter        | Type                                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Component`      | `T`                                                                                                               |
| `propsAreEqual`? | (`prevProps`: `Readonly`\<`ComponentProps`\<`T`>>, `nextProps`: `Readonly`\<`ComponentProps`\<`T`>>) => `boolean` |

### Returns

`MemoExoticComponent`\<`T`>

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1771



---
url: /api/react/Function.runOnBackground.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / runOnBackground

# Function: runOnBackground()

```ts
function runOnBackground<R, Fn>(f: Fn): (...args: Parameters<Fn>) => Promise<R>
```

`runOnBackground` allows triggering js functions on the background thread asynchronously.

## Type Parameters

| Type Parameter                              |
| ------------------------------------------- |
| `R`                                         |
| `Fn` _extends_ (...`args`: `any`\[]) => `R` |

## Parameters

| Parameter | Type | Description                   |
| --------- | ---- | ----------------------------- |
| `f`       | `Fn` | The js function to be called. |

## Returns

`Function`

A function. Calling which with the arguments to be passed to the js function to trigger it on the background thread. This function returns a promise that resolves to the return value of the js function.

### Parameters

| Parameter | Type                |
| --------- | ------------------- |
| ...`args` | `Parameters`\<`Fn`> |

### Returns

`Promise`\<`R`>

## Example

```ts
import { runOnBackground } from '@lynx-js/react';

async function someMainthreadFunction() {
  'main thread';
  const fn = runOnBackground(() => {
    return 'hello';
  });
  const result = await fn();
}
```

## Defined in

@lynx-js/react/runtime/lib/worklet/call/runOnBackground.d.ts:19



---
url: /api/react/Function.runOnMainThread.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / runOnMainThread

# Function: runOnMainThread()

```ts
function runOnMainThread<R, Fn>(fn: Fn): (...args: Parameters<Fn>) => Promise<R>
```

`runOnMainThread` allows triggering main thread functions on the main thread asynchronously.

## Type Parameters

| Type Parameter                              |
| ------------------------------------------- |
| `R`                                         |
| `Fn` _extends_ (...`args`: `any`\[]) => `R` |

## Parameters

| Parameter | Type | Description                             |
| --------- | ---- | --------------------------------------- |
| `fn`      | `Fn` | The main thread functions to be called. |

## Returns

`Function`

A function. Calling which with the arguments to be passed to the main thread function to trigger it on the main thread. This function returns a promise that resolves to the return value of the main thread function.

### Parameters

| Parameter | Type                |
| --------- | ------------------- |
| ...`args` | `Parameters`\<`Fn`> |

### Returns

`Promise`\<`R`>

## Example

```ts
import { runOnMainThread } from '@lynx-js/react';

async function someFunction() {
  const fn = runOnMainThread(() => {
    'main thread';
    return 'hello';
  });
  const result = await fn();
}
```

## Defined in

@lynx-js/react/runtime/lib/worklet/call/runOnMainThread.d.ts:19



---
url: /api/react/Function.useCallback.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useCallback

# Function: useCallback()

```ts
function useCallback<T>(callback: T, deps: DependencyList): T
```

`useCallback` will return a memoized version of the callback that only changes if one of the `inputs`
has changed.

## Type Parameters

| Type Parameter           |
| ------------------------ |
| `T` _extends_ `Function` |

## Parameters

| Parameter  | Type             |
| ---------- | ---------------- |
| `callback` | `T`              |
| `deps`     | `DependencyList` |

## Returns

`T`

## Version

16.8.0

## See

[https://react.dev/reference/react/useCallback](https://react.dev/reference/react/useCallback)

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:2062



---
url: /api/react/Function.useContext.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useContext

# Function: useContext()

```ts
function useContext<T>(context: Context<T>): T
```

Accepts a context object (the value returned from `React.createContext`) and returns the current
context value, as given by the nearest context provider for the given context.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter | Type            |
| --------- | --------------- |
| `context` | `Context`\<`T`> |

## Returns

`T`

## Version

16.8.0

## See

[https://react.dev/reference/react/useContext](https://react.dev/reference/react/useContext)

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1869



---
url: /api/react/Function.useDebugValue.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useDebugValue

# Function: useDebugValue()

```ts
function useDebugValue<T>(value: T, format?: (value: T) => any): void
```

`useDebugValue` can be used to display a label for custom hooks in React DevTools.

NOTE: We don’t recommend adding debug values to every custom hook.
It’s most valuable for custom hooks that are part of shared libraries.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter | Type                    |
| --------- | ----------------------- |
| `value`   | `T`                     |
| `format`? | (`value`: `T`) => `any` |

## Returns

`void`

## Version

16.8.0

## See

[https://react.dev/reference/react/useDebugValue](https://react.dev/reference/react/useDebugValue)

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:2082



---
url: /api/react/Function.useEffect.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useEffect

# Function: useEffect()

```ts
function useEffect(effect: EffectCallback, deps?: DependencyList): void
```

Accepts a function that contains imperative, possibly effectful code.
The effects run after main thread dom update without blocking it.

## Parameters

| Parameter | Type             | Description                                                                         |
| --------- | ---------------- | ----------------------------------------------------------------------------------- |
| `effect`  | `EffectCallback` | Imperative function that can return a cleanup function                              |
| `deps`?   | `DependencyList` | If present, effect will only activate if the values in the list change (using ===). |

## Returns

`void`

## Defined in

@lynx-js/react/runtime/lib/hooks/react.d.ts:25



---
url: /api/react/Function.useImperativeHandle.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useImperativeHandle

# Function: useImperativeHandle()

```ts
function useImperativeHandle<T, R>(
   ref: Ref<T>, 
   init: () => R, 
   deps?: DependencyList): void
```

`useImperativeHandle` customizes the instance value that is exposed to parent components when using
`ref`. As always, imperative code using refs should be avoided in most cases.

`useImperativeHandle` should be used with `React.forwardRef`.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |
| `R`            |

## Parameters

| Parameter | Type             |
| --------- | ---------------- |
| `ref`     | `Ref`\<`T`>      |
| `init`    | () => `R`        |
| `deps`?   | `DependencyList` |

## Returns

`void`

## Version

16.8.0

## See

[https://react.dev/reference/react/useImperativeHandle](https://react.dev/reference/react/useImperativeHandle)

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:2049



---
url: /api/react/Function.useInitData.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useInitData

# Function: useInitData()

```ts
function useInitData(): InitData
```

A React Hooks for you to get `initData`.
If `initData` is changed, a re-render will be triggered automatically.

## Returns

[`InitData`](/api/react/Interface.InitData.md)

## Example

```ts
function App() {
  const initData = useInitData();

  initData.someProperty // use it
}
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:123



---
url: /api/react/Function.useInitDataChanged.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useInitDataChanged

# Function: useInitDataChanged()

```ts
function useInitDataChanged(callback: (data: InitData) => void): void
```

A React Hooks for you to get notified when `initData` changed.

## Parameters

| Parameter  | Type                                                               |
| ---------- | ------------------------------------------------------------------ |
| `callback` | (`data`: [`InitData`](/api/react/Interface.InitData.md)) => `void` |

## Returns

`void`

## Example

```ts
function App() {
  useInitDataChanged((data) => {
    data.someProperty // can use it
  })
}
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:137



---
url: /api/react/Function.useLayoutEffect.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useLayoutEffect

# Function: ~~useLayoutEffect()~~

```ts
function useLayoutEffect(effect: EffectCallback, deps?: DependencyList): void
```

`useLayoutEffect` is now an alias of `useEffect`. Use `useEffect` instead.

Accepts a function that contains imperative, possibly effectful code. The effects run after main thread dom update without blocking it.

## Parameters

| Parameter | Type             | Description                                                                         |
| --------- | ---------------- | ----------------------------------------------------------------------------------- |
| `effect`  | `EffectCallback` | Imperative function that can return a cleanup function                              |
| `deps`?   | `DependencyList` | If present, effect will only activate if the values in the list change (using ===). |

## Returns

`void`

## Deprecated

`useLayoutEffect` in the background thread cannot offer the precise timing for reading layout information and synchronously re-render, which is different from React.

## Defined in

@lynx-js/react/runtime/lib/hooks/react.d.ts:15



---
url: /api/react/Function.useLynxGlobalEventListener.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useLynxGlobalEventListener

# Function: useLynxGlobalEventListener()

```ts
function useLynxGlobalEventListener<T>(eventName: string, listener: T): void
```

`useLynxGlobalEventListener` help you `addListener` as early as possible.

## Type Parameters

| Type Parameter                                |
| --------------------------------------------- |
| `T` _extends_ (...`args`: `any`\[]) => `void` |

## Parameters

| Parameter   | Type     | Description          |
| ----------- | -------- | -------------------- |
| `eventName` | `string` | Event name to listen |
| `listener`  | `T`      | Event handler        |

## Returns

`void`

## Example

Use this hooks to listen to event 'exposure' and event 'disexposure'

```jsx
function App() {
  useLynxGlobalEventListener('exposure', (e) => {
    console.log("exposure", e)
  })
  useLynxGlobalEventListener('disexposure', (e) => {
    console.log("disexposure", e)
  })
  return (
    <view
      style='width: 100px; height: 100px; background-color: red;'
      exposure-id='a'
    />
  )
}
```

## Defined in

@lynx-js/react/runtime/lib/hooks/useLynxGlobalEventListener.d.ts:29



---
url: /api/react/Function.useMainThreadRef.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useMainThreadRef

# Function: useMainThreadRef()

## useMainThreadRef(initValue)

```ts
function useMainThreadRef<T>(initValue: T): MainThreadRef<T>
```

Create A `MainThreadRef`.

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

It is a hook and it should only be called at the top level of your component.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter   | Type | Description                            |
| ----------- | ---- | -------------------------------------- |
| `initValue` | `T`  | The init value of the `MainThreadRef`. |

### Returns

[`MainThreadRef`](/api/react/Class.MainThreadRef.md)\<`T`>

### Example

```ts
import { useMainThreadRef } from '@lynx-js/react'
import type { MainThread } from '@lynx-js/types'

export function App() {
  const ref = useMainThreadRef<MainThread.Element>(null)

  const handleTap = () => {
    'main thread'
    ref.current?.setStyleProperty('background-color', 'blue')
  }

  return (
    <view
      main-thread:ref={ref}
      main-thread:bindtap={handleTap}
      style={{ width: '300px', height: '300px' }}
    />
  )
}
```

### Defined in

@lynx-js/react/runtime/lib/worklet/ref/workletRef.d.ts:55

## useMainThreadRef(initValue)

```ts
function useMainThreadRef<T>(initValue: T): RefObject<T>
```

Create A `MainThreadRef`.

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

It is a hook and it should only be called at the top level of your component.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter   | Type | Description                            |
| ----------- | ---- | -------------------------------------- |
| `initValue` | `T`  | The init value of the `MainThreadRef`. |

### Returns

`RefObject`\<`T`>

### Example

```ts
import { useMainThreadRef } from '@lynx-js/react'
import type { MainThread } from '@lynx-js/types'

export function App() {
  const ref = useMainThreadRef<MainThread.Element>(null)

  const handleTap = () => {
    'main thread'
    ref.current?.setStyleProperty('background-color', 'blue')
  }

  return (
    <view
      main-thread:ref={ref}
      main-thread:bindtap={handleTap}
      style={{ width: '300px', height: '300px' }}
    />
  )
}
```

### Defined in

@lynx-js/react/runtime/lib/worklet/ref/workletRef.d.ts:94

## useMainThreadRef()

```ts
function useMainThreadRef<T>(): MainThreadRef<T | undefined>
```

Create A `MainThreadRef`.

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

It is a hook and it should only be called at the top level of your component.

### Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `T`            | `undefined`  |

### Returns

[`MainThreadRef`](/api/react/Class.MainThreadRef.md)\<`T` | `undefined`>

### Example

```ts
import { useMainThreadRef } from '@lynx-js/react'
import type { MainThread } from '@lynx-js/types'

export function App() {
  const ref = useMainThreadRef<MainThread.Element>(null)

  const handleTap = () => {
    'main thread'
    ref.current?.setStyleProperty('background-color', 'blue')
  }

  return (
    <view
      main-thread:ref={ref}
      main-thread:bindtap={handleTap}
      style={{ width: '300px', height: '300px' }}
    />
  )
}
```

### Defined in

@lynx-js/react/runtime/lib/worklet/ref/workletRef.d.ts:131



---
url: /api/react/Function.useMemo.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useMemo

# Function: useMemo()

```ts
function useMemo<T>(factory: () => T, deps: DependencyList): T
```

`useMemo` will only recompute the memoized value when one of the `deps` has changed.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter | Type             |
| --------- | ---------------- |
| `factory` | () => `T`        |
| `deps`    | `DependencyList` |

## Returns

`T`

## Version

16.8.0

## See

[https://react.dev/reference/react/useMemo](https://react.dev/reference/react/useMemo)

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:2070



---
url: /api/react/Function.useReducer.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useReducer

# Function: useReducer()

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R, I>(
   reducer: R, 
   initializerArg: I, 
   initializer: (arg: I) => ReducerStateWithoutAction<R>): [ReducerStateWithoutAction<R>, DispatchWithoutAction]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                               |
| -------------------------------------------- |
| `R` _extends_ `ReducerWithoutAction`\<`any`> |
| `I`                                          |

### Parameters

| Parameter        | Type                                              |
| ---------------- | ------------------------------------------------- |
| `reducer`        | `R`                                               |
| `initializerArg` | `I`                                               |
| `initializer`    | (`arg`: `I`) => `ReducerStateWithoutAction`\<`R`> |

### Returns

\[`ReducerStateWithoutAction`\<`R`>, `DispatchWithoutAction`]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1896

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R>(
   reducer: R, 
   initializerArg: ReducerStateWithoutAction<R>, 
   initializer?: undefined): [ReducerStateWithoutAction<R>, DispatchWithoutAction]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                               |
| -------------------------------------------- |
| `R` _extends_ `ReducerWithoutAction`\<`any`> |

### Parameters

| Parameter        | Type                              |
| ---------------- | --------------------------------- |
| `reducer`        | `R`                               |
| `initializerArg` | `ReducerStateWithoutAction`\<`R`> |
| `initializer`?   | `undefined`                       |

### Returns

\[`ReducerStateWithoutAction`\<`R`>, `DispatchWithoutAction`]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1912

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R, I>(
   reducer: R, 
   initializerArg: I & ReducerState<R>, 
   initializer: (arg: I & ReducerState<R>) => ReducerState<R>): [ReducerState<R>, Dispatch<ReducerAction<R>>]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                         |
| -------------------------------------- |
| `R` _extends_ `Reducer`\<`any`, `any`> |
| `I`                                    |

### Parameters

| Parameter        | Type                                                        |
| ---------------- | ----------------------------------------------------------- |
| `reducer`        | `R`                                                         |
| `initializerArg` | `I` & `ReducerState`\<`R`>                                  |
| `initializer`    | (`arg`: `I` & `ReducerState`\<`R`>) => `ReducerState`\<`R`> |

### Returns

\[`ReducerState`\<`R`>, `Dispatch`\<`ReducerAction`\<`R`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1930

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R, I>(
   reducer: R, 
   initializerArg: I, 
   initializer: (arg: I) => ReducerState<R>): [ReducerState<R>, Dispatch<ReducerAction<R>>]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                         |
| -------------------------------------- |
| `R` _extends_ `Reducer`\<`any`, `any`> |
| `I`                                    |

### Parameters

| Parameter        | Type                                 |
| ---------------- | ------------------------------------ |
| `reducer`        | `R`                                  |
| `initializerArg` | `I`                                  |
| `initializer`    | (`arg`: `I`) => `ReducerState`\<`R`> |

### Returns

\[`ReducerState`\<`R`>, `Dispatch`\<`ReducerAction`\<`R`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1946

## useReducer(reducer, initialState, initializer)

```ts
function useReducer<R>(
   reducer: R, 
   initialState: ReducerState<R>, 
   initializer?: undefined): [ReducerState<R>, Dispatch<ReducerAction<R>>]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                         |
| -------------------------------------- |
| `R` _extends_ `Reducer`\<`any`, `any`> |

### Parameters

| Parameter      | Type                 |
| -------------- | -------------------- |
| `reducer`      | `R`                  |
| `initialState` | `ReducerState`\<`R`> |
| `initializer`? | `undefined`          |

### Returns

\[`ReducerState`\<`R`>, `Dispatch`\<`ReducerAction`\<`R`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1971



---
url: /api/react/Function.useRef.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useRef

# Function: useRef()

## useRef(initialValue)

```ts
function useRef<T>(initialValue: T): MutableRefObject<T>
```

`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
(`initialValue`). The returned object will persist for the full lifetime of the component.

Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter      | Type |
| -------------- | ---- |
| `initialValue` | `T`  |

### Returns

`MutableRefObject`\<`T`>

### Version

16.8.0

### See

[https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1986

## useRef(initialValue)

```ts
function useRef<T>(initialValue: T): RefObject<T>
```

`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
(`initialValue`). The returned object will persist for the full lifetime of the component.

Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.

Usage note: if you need the result of useRef to be directly mutable, include `| null` in the type
of the generic argument.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter      | Type |
| -------------- | ---- |
| `initialValue` | `T`  |

### Returns

`RefObject`\<`T`>

### Version

16.8.0

### See

[https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:2001

## useRef()

```ts
function useRef<T>(): MutableRefObject<T | undefined>
```

`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
(`initialValue`). The returned object will persist for the full lifetime of the component.

Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.

### Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `T`            | `undefined`  |

### Returns

`MutableRefObject`\<`T` | `undefined`>

### Version

16.8.0

### See

[https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:2014



---
url: /api/react/Function.useState.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useState

# Function: useState()

## useState(initialState)

```ts
function useState<S>(initialState: S | () => S): [S, Dispatch<SetStateAction<S>>]
```

Returns a stateful value, and a function to update it.

### Type Parameters

| Type Parameter |
| -------------- |
| `S`            |

### Parameters

| Parameter      | Type             |
| -------------- | ---------------- |
| `initialState` | `S` \| () => `S` |

### Returns

\[`S`, `Dispatch`\<`SetStateAction`\<`S`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useState](https://react.dev/reference/react/useState)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1876

## useState()

```ts
function useState<S>(): [S | undefined, Dispatch<SetStateAction<S | undefined>>]
```

Returns a stateful value, and a function to update it.

### Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `S`            | `undefined`  |

### Returns

\[`S` | `undefined`, `Dispatch`\<`SetStateAction`\<`S` | `undefined`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useState](https://react.dev/reference/react/useState)

### Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:1884



---
url: /api/react/Function.useSyncExternalStore.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / useSyncExternalStore

# Function: useSyncExternalStore()

```ts
function useSyncExternalStore<Snapshot>(
   subscribe: (onStoreChange: () => void) => () => void, 
   getSnapshot: () => Snapshot, 
   getServerSnapshot?: () => Snapshot): Snapshot
```

## Type Parameters

| Type Parameter |
| -------------- |
| `Snapshot`     |

## Parameters

| Parameter            | Type                                            | Description |
| -------------------- | ----------------------------------------------- | ----------- |
| `subscribe`          | (`onStoreChange`: () => `void`) => () => `void` |             |
| `getSnapshot`        | () => `Snapshot`                                |             |
| `getServerSnapshot`? | () => `Snapshot`                                | -           |

## Returns

`Snapshot`

## See

[https://github.com/reactwg/react-18/discussions/86](https://github.com/reactwg/react-18/discussions/86)

## Defined in

.pnpm/@types+react\@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:2168



---
url: /api/react/Function.withInitDataInState.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / withInitDataInState

# Function: withInitDataInState()

```ts
function withInitDataInState<P, S>(App: ComponentClass<P, S>): ComponentClass<P, S>
```

Higher-Order Component (HOC) that injects `initData` into the state of the given class component.

This HOC checks if the provided component is a class component. If it is, it wraps the component
and injects the `initData` into its state. It also adds a listener
to update the state when data changes, and removes the listener when the component unmounts.

## Type Parameters

| Type Parameter | Description                                     |
| -------------- | ----------------------------------------------- |
| `P`            | The type of the props of the wrapped component. |
| `S`            | The type of the state of the wrapped component. |

## Parameters

| Parameter | Type                        | Description                                   |
| --------- | --------------------------- | --------------------------------------------- |
| `App`     | `ComponentClass`\<`P`, `S`> | The class component to be wrapped by the HOC. |

## Returns

`ComponentClass`\<`P`, `S`>

The original component if it is not a class component, otherwise a new class component
with `initData` injection and state update functionality.

## Example

```typescript
class App extends React.Component<MyProps, MyState> {
  // component implementation
}

export default withInitDataInState(App);
```

## Defined in

@lynx-js/react/runtime/lib/compat/initData.d.ts:44



---
url: /api/react/Interface.DataProcessorDefinition.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / DataProcessorDefinition

# Interface: DataProcessorDefinition

Definition of DataProcessor(s)

## Properties

### dataProcessors?

```ts
optional dataProcessors: DataProcessors;
```

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:254

***

### defaultDataProcessor()?

```ts
optional defaultDataProcessor: (rawInitData: InitDataRaw) => InitData;
```

You can custom input and output type of `defaultDataProcessor` by extends [InitDataRaw](/api/react/Interface.InitDataRaw.md) and [InitData](/api/react/Interface.InitData.md)

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).

#### Parameters

| Parameter     | Type                                                 | Description                      |
| ------------- | ---------------------------------------------------- | -------------------------------- |
| `rawInitData` | [`InitDataRaw`](/api/react/Interface.InitDataRaw.md) | initData passed from native code |

#### Returns

[`InitData`](/api/react/Interface.InitData.md)

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:248



---
url: /api/react/Interface.DataProcessors.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / DataProcessors

# Interface: DataProcessors

The data processors that registered with [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).

## Example

Extending `dataProcessors` interface

```ts
import type { DataProcessors as WellKnownDataProcessors } from '@lynx-js/react';

declare module '@lynx-js/react' {
  interface DataProcessors extends WellKnownDataProcessors {
    foo(bar: string): number;
  }
}
```

Then you can use `lynx.registerDataProcessors` with types.

```js
lynx.registerDataProcessors({
  dataProcessors: {
    foo(bar) {
      return 1;
    }
  }
})
```

## Indexable

\[`processorName`: `string`]: (...`args`: `any`\[]) => `any`

## Methods

### getScreenMetricsOverride()?

```ts
optional getScreenMetricsOverride(metrics: object): object
```

Optional processor to override screen metrics used by the app

#### Parameters

| Parameter        | Type     | Description                              |
| ---------------- | -------- | ---------------------------------------- |
| `metrics`        | `object` | The physical screen dimensions in pixels |
| `metrics.height` | `number` | The physical pixel height of the screen  |
| `metrics.width`  | `number` | The physical pixel width of the screen   |

#### Returns

`object`

New screen dimensions to be used by the app

##### height

```ts
height: number;
```

##### width

```ts
width: number;
```

#### Example

```ts
lynx.registerDataProcessors({
  dataProcessors: {
    getScreenMetricsOverride: (metrics) => {
      // Force a specific aspect ratio
      return {
        width: metrics.width,
        height: metrics.width * (16/9)
      };
    }
  }
});
```

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:212



---
url: /api/react/Interface.InitData.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / InitData

# Interface: InitData

The interface you can extends so that the `defaultDataProcessor` returning value can be customized

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).



---
url: /api/react/Interface.InitDataRaw.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / InitDataRaw

# Interface: InitDataRaw

The interface you can extends so that the `defaultDataProcessor` parameter can be customized

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).



---
url: /api/react/Interface.Lynx.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / Lynx

# Interface: Lynx

APIs under `lynx` global variable that added by ReactLynx.

## Example

```ts
lynx.registerDataProcessors(...);
lynx.querySelector(...);
lynx.querySelectorAll(...);
```

## Properties

### querySelector()

```ts
querySelector: (selector: string) => null | Element;
```

Select the first element matching the given CSS selector in the page.

#### Parameters

| Parameter  | Type     | Description          |
| ---------- | -------- | -------------------- |
| `selector` | `string` | CSS Selector string. |

#### Returns

`null` | `Element`

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:323

***

### querySelectorAll()

```ts
querySelectorAll: (selector: string) => Element[];
```

Select all the elements matching the given CSS selector in the page.

#### Parameters

| Parameter  | Type     | Description          |
| ---------- | -------- | -------------------- |
| `selector` | `string` | CSS Selector string. |

#### Returns

`Element`\[]

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:330

***

### registerDataProcessors()

```ts
registerDataProcessors: (dataProcessorDefinition?: DataProcessorDefinition) => void;
```

Register DataProcessors. You MUST call this before `root.render()`.

#### Parameters

| Parameter                  | Type                                                                         |
| -------------------------- | ---------------------------------------------------------------------------- |
| `dataProcessorDefinition`? | [`DataProcessorDefinition`](/api/react/Interface.DataProcessorDefinition.md) |

#### Returns

`void`

#### Examples

You MUST call `lynx.registerDataProcessors` before calling `root.render()`.

```ts
import { root } from "@lynx-js/react"

// You MUST call this before `root.render()`
lynx.registerDataProcessors({
  defaultDataProcessor: () => {...} // default DataProcessor
  dataProcessors: {
    getScreenMetricsOverride: () => {...} // named DataProcessor
  }
})

root.render(<App/>);
```

If you have a class component with `static defaultDataProcessor`
or `static dataProcessors`, you can use it to register DataProcessors.

```ts
import { root, Component } from "@lynx-js/react"

class App extends Component {
  static defaultDataProcessor() {
     ...
  }

  static dataProcessors = {
    getScreenMetricsOverride() {
      ...
    }
  }
}

lynx.registerDataProcessors(App); // You can pass `App` because it has the required shape
root.render(<App/>);
```

For developers who want fully typed `defaultDataProcessor`,
they can achieve it by extends interface `InitDataRaw` and `InitData`.

```ts
import { root } from "@lynx-js/react"

interface ExistingInterface {
  somePropertyFromExistingInterface: number
}

declare module '@lynx-js/react' {
  interface InitDataRaw extends ExistingInterface {
    someAnotherCustomProperty: string
  }
}

lynx.registerDataProcessors({
  defaultDataProcessor: (initDataRaw) => {
    initDataRaw.somePropertyFromExistingInterface // will be typed
  }
})

```

For developers who want fully typed `defaultDataProcessor`,
they can achieve it by extends interface `InitDataRaw` and `InitData`.

```ts
import { root, useInitData } from "@lynx-js/react"

interface AnotherExistingInterface {
  someAnotherPropertyFromExistingInterface: number
}

declare module '@lynx-js/react' {
  interface InitData extends AnotherExistingInterface {
    someCustomProperty: string
  }
}

root.registerDataProcessors({
  defaultDataProcessor: () => {
    return {
      someCustomProperty: 'value', // will be typed
      someAnotherPropertyFromExistingInterface: 1, // will be typed
    }
  }
})

function App() {
  const initData = useInitData();

  initData.someCustomProperty // will be typed
  initData.someAnotherPropertyFromExistingInterface // will be typed
}

```

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:384

***

### triggerGlobalEventFromLepus()

```ts
triggerGlobalEventFromLepus: (eventName: string, params: any) => void;
```

An alias of `lynx.getJSModule("GlobalEventEmitter").trigger(eventName, params)` only in Lepus

#### Parameters

| Parameter   | Type     |
| ----------- | -------- |
| `eventName` | `string` |
| `params`    | `any`    |

#### Returns

`void`

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:275



---
url: /api/react/Interface.Root.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / Root

# Interface: Root

The default root exported by `@lynx-js/react` for you to render a JSX

## Properties

### ~~registerDataProcessors()~~

```ts
registerDataProcessors: (dataProcessorDefinition: DataProcessorDefinition) => void;
```

Register DataProcessors. You MUST call this before `root.render()`.

#### Parameters

| Parameter                 | Type                                                                         |
| ------------------------- | ---------------------------------------------------------------------------- |
| `dataProcessorDefinition` | [`DataProcessorDefinition`](/api/react/Interface.DataProcessorDefinition.md) |

#### Returns

`void`

#### Deprecated

use [lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors) instead

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:59

***

### render()

```ts
render: (jsx: ReactNode) => void;
```

Use this API to pass in your JSX to render

#### Parameters

| Parameter | Type        |
| --------- | ----------- |
| `jsx`     | `ReactNode` |

#### Returns

`void`

#### Examples

```ts
import { root } from "@lynx-js/react"

function App() {
  // Your app
  return <view>...</view>
}

root.render(<App/>);
```

```tsx
import { root } from "@lynx-js/react"

function App() {
  // Your app
  return <view>...</view>
}

if (__MAIN_THREAD__) {
  root.render(
    <DataProvider data={DEFAULT_DATA}>
       <App/>
    </DataProvider>
  );
} else if (__BACKGROUND__) {
  fetchData().then((data) => {
    root.render(
      <DataProvider data={data}>
         <App/>
      </DataProvider>
    ); // You can render later after your data is ready
  })
}
```

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:53



---
url: /api/react/Variable.root.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[@lynx-js/react](/api/react/index.md) / root

# Variable: root

```ts
const root: Root;
```

The default and only root of ReactLynx for you to render JSX

## Example

```ts
import { root } from "@lynx-js/react"
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:70



---
url: /api/react/index.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


# @lynx-js/react

Welcome to the API reference for `@lynx-js/react`, the package that provides the ReactLynx framework. For an introduction to ReactLynx, please visit the [ReactLynx Guides](/react/index.md).

## React APIs

ReactLynx is based on the React 17 API. You can expect the React APIs provided by `@lynx-js/react` to be fully compatible with React 17 or [Preact](https://preactjs.com/guide/v10/switching-to-preact/).

Here is an overview of the APIs provided by ReactLynx. These APIs will behave consistently with those described in the [official React reference](https://react.dev/reference/react) unless otherwise specified. We will also highlight any special considerations for using them on the Lynx platform.

:::details Why is it based on compatibility with React 17?
React officially entered the "concurrent" era starting with [React 18](https://react.dev/blog/2022/03/29/react-v18). Concurrent React features, represented by APIs such as `useTransition` and `useDeferredValue`, have very strict requirements for the scheduling method and concurrency model of the execution environment—including dependencies on or overwriting of browser Web APIs, dependencies on the new architecture of React Native, and more. Lynx has its own characteristics and considerations in architectural evolution, so we chose React 17 as the foundation for ReactLynx, evolving into the Lynx system while retaining the React programming model.

At the same time, we will continue to pay attention to subsequent React advancements, such as [React 19](https://react.dev/blog/2024/04/25/react-19) and [React Compiler](https://react.dev/learn/react-compiler), and attempt to integrate the parts that do not depend on the concurrent architecture into the ReactLynx system.
:::

## Documents

| Document                                                  | Description |
| --------------------------------------------------------- | ----------- |
| [built-in-macros](/api/react/Document.built-in-macros.md) | -           |
| [directives](/api/react/Document.directives.md)           | -           |

## Classes

| Class                                              | Description                                                                                                                                                                                                                                                       |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Component](/api/react/Class.Component.md)         | -                                                                                                                                                                                                                                                                 |
| [MainThreadRef](/api/react/Class.MainThreadRef.md) | A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve states between main thread function calls. The data saved in `current` property of the `MainThreadRef` can be read and written in multiple main thread functions. |
| [PureComponent](/api/react/Class.PureComponent.md) | -                                                                                                                                                                                                                                                                 |

## Interfaces

| Interface                                                                  | Description                                                                                                                  |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [DataProcessorDefinition](/api/react/Interface.DataProcessorDefinition.md) | Definition of DataProcessor(s)                                                                                               |
| [DataProcessors](/api/react/Interface.DataProcessors.md)                   | The data processors that registered with [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors). |
| [InitData](/api/react/Interface.InitData.md)                               | The interface you can extends so that the `defaultDataProcessor` returning value can be customized                           |
| [InitDataRaw](/api/react/Interface.InitDataRaw.md)                         | The interface you can extends so that the `defaultDataProcessor` parameter can be customized                                 |
| [Lynx](/api/react/Interface.Lynx.md)                                       | APIs under `lynx` global variable that added by ReactLynx.                                                                   |
| [Root](/api/react/Interface.Root.md)                                       | The default root exported by `@lynx-js/react` for you to render a JSX                                                        |

## Variables

| Variable                            | Description                                                  |
| ----------------------------------- | ------------------------------------------------------------ |
| [root](/api/react/Variable.root.md) | The default and only root of ReactLynx for you to render JSX |

## Functions

| Function                                                                        | Description                                                                                                                                                                                      |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [cloneElement](/api/react/Function.cloneElement.md)                             | -                                                                                                                                                                                                |
| [createContext](/api/react/Function.createContext.md)                           | Lets you create a Context that components can provide or read.                                                                                                                                   |
| [createElement](/api/react/Function.createElement.md)                           | -                                                                                                                                                                                                |
| [createRef](/api/react/Function.createRef.md)                                   | -                                                                                                                                                                                                |
| [forwardRef](/api/react/Function.forwardRef.md)                                 | Lets your component expose a DOM node to a parent component using a ref.                                                                                                                         |
| [Fragment](/api/react/Function.Fragment.md)                                     | Lets you group elements without a wrapper node.                                                                                                                                                  |
| [isValidElement](/api/react/Function.isValidElement.md)                         | -                                                                                                                                                                                                |
| [lazy](/api/react/Function.lazy.md)                                             | Lets you defer loading a component’s code until it is rendered for the first time.                                                                                                               |
| [memo](/api/react/Function.memo.md)                                             | Lets you skip re-rendering a component when its props are unchanged.                                                                                                                             |
| [runOnBackground](/api/react/Function.runOnBackground.md)                       | `runOnBackground` allows triggering js functions on the background thread asynchronously.                                                                                                        |
| [runOnMainThread](/api/react/Function.runOnMainThread.md)                       | `runOnMainThread` allows triggering main thread functions on the main thread asynchronously.                                                                                                     |
| [Suspense](/api/react/Function.Suspense.md)                                     | Lets you display a fallback until its children have finished loading.                                                                                                                            |
| [useCallback](/api/react/Function.useCallback.md)                               | `useCallback` will return a memoized version of the callback that only changes if one of the `inputs` has changed.                                                                               |
| [useContext](/api/react/Function.useContext.md)                                 | Accepts a context object (the value returned from `React.createContext`) and returns the current context value, as given by the nearest context provider for the given context.                  |
| [useDebugValue](/api/react/Function.useDebugValue.md)                           | `useDebugValue` can be used to display a label for custom hooks in React DevTools.                                                                                                               |
| [useEffect](/api/react/Function.useEffect.md)                                   | Accepts a function that contains imperative, possibly effectful code. The effects run after main thread dom update without blocking it.                                                          |
| [useImperativeHandle](/api/react/Function.useImperativeHandle.md)               | `useImperativeHandle` customizes the instance value that is exposed to parent components when using `ref`. As always, imperative code using refs should be avoided in most cases.                |
| [useInitData](/api/react/Function.useInitData.md)                               | A React Hooks for you to get `initData`. If `initData` is changed, a re-render will be triggered automatically.                                                                                  |
| [useInitDataChanged](/api/react/Function.useInitDataChanged.md)                 | A React Hooks for you to get notified when `initData` changed.                                                                                                                                   |
| [useLayoutEffect](/api/react/Function.useLayoutEffect.md)                       | `useLayoutEffect` is now an alias of `useEffect`. Use `useEffect` instead.                                                                                                                       |
| [useLynxGlobalEventListener](/api/react/Function.useLynxGlobalEventListener.md) | `useLynxGlobalEventListener` help you `addListener` as early as possible.                                                                                                                        |
| [useMainThreadRef](/api/react/Function.useMainThreadRef.md)                     | Create A `MainThreadRef`.                                                                                                                                                                        |
| [useMemo](/api/react/Function.useMemo.md)                                       | `useMemo` will only recompute the memoized value when one of the `deps` has changed.                                                                                                             |
| [useReducer](/api/react/Function.useReducer.md)                                 | An alternative to `useState`.                                                                                                                                                                    |
| [useRef](/api/react/Function.useRef.md)                                         | `useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. |
| [useState](/api/react/Function.useState.md)                                     | Returns a stateful value, and a function to update it.                                                                                                                                           |
| [useSyncExternalStore](/api/react/Function.useSyncExternalStore.md)             | -                                                                                                                                                                                                |
| [withInitDataInState](/api/react/Function.withInitDataInState.md)               | Higher-Order Component (HOC) that injects `initData` into the state of the given class component.                                                                                                |

## Components

| Function                                                    | Description                                                                                                                                                                                      |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [InitDataConsumer](/api/react/Function.InitDataConsumer.md) | The [Consumer](https://react.dev/reference/react/createContext#consumer) Component that provide `initData`. This should be used with [InitDataProvider](/api/react/Function.InitDataProvider.md) |
| [InitDataProvider](/api/react/Function.InitDataProvider.md) | The [Provider](https://react.dev/reference/react/createContext#provider) Component that provide `initData`, you must wrap your JSX inside it                                                     |



---
url: /api/reactlynx-testing-library/Class.LynxTestingEnv.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / LynxTestingEnv

# Class: LynxTestingEnv

A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md),
notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js.

## Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';

const lynxTestingEnv = new LynxTestingEnv();

lynxTestingEnv.switchToMainThread();
// use the main thread Element PAPI
const page = __CreatePage('0', 0);
const view = __CreateView(0);
__AppendElement(page, view);

```

## Constructors

### new LynxTestingEnv()

```ts
new LynxTestingEnv(): LynxTestingEnv
```

#### Returns

[`LynxTestingEnv`](/api/reactlynx-testing-library/Class.LynxTestingEnv.md)

#### Defined in

index.d.ts:892

## Properties

### backgroundThread

```ts
backgroundThread: LynxGlobalThis;
```

The global object for the background thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';

const lynxTestingEnv = new LynxTestingEnv();

lynxTestingEnv.switchToBackgroundThread();
// use the background thread global object
globalThis.lynxCoreInject.tt.OnLifecycleEvent(...args);
```

#### Defined in

index.d.ts:872

***

### jsdom

```ts
jsdom: JSDOM;
```

#### Defined in

index.d.ts:891

***

### mainThread

```ts
mainThread: LynxGlobalThis & ElementTreeGlobals;
```

The global object for the main thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';

const lynxTestingEnv = new LynxTestingEnv();

lynxTestingEnv.switchToMainThread();
// use the main thread global object
const page = globalThis.__CreatePage('0', 0);
const view = globalThis.__CreateView(0);
globalThis.__AppendElement(page, view);
```

#### Defined in

index.d.ts:890

## Methods

### clearGlobal()

```ts
clearGlobal(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:896

***

### injectGlobals()

```ts
injectGlobals(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:893

***

### reset()

```ts
reset(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:897

***

### switchToBackgroundThread()

```ts
switchToBackgroundThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:894

***

### switchToMainThread()

```ts
switchToMainThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:895



---
url: /api/reactlynx-testing-library/Function.buildQueries.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / buildQueries

# Function: buildQueries()

```ts
function buildQueries<Arguments>(
   queryAllBy: GetAllBy<Arguments>, 
   getMultipleError: GetErrorFunction<Arguments>, 
getMissingError: GetErrorFunction<Arguments>): BuiltQueryMethods<Arguments>
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Parameters

| Parameter          | Type                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `queryAllBy`       | [`GetAllBy`](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md)\<`Arguments`>                 |
| `getMultipleError` | [`GetErrorFunction`](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)\<`Arguments`> |
| `getMissingError`  | [`GetErrorFunction`](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)\<`Arguments`> |

## Returns

[`BuiltQueryMethods`](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md)\<`Arguments`>

## Defined in

index.d.ts:193



---
url: /api/reactlynx-testing-library/Function.cleanup.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / cleanup

# Function: cleanup()

```ts
function cleanup(): void
```

Cleanup elements rendered to the page and Preact trees that were mounted with render.

## Returns

`void`

## Defined in

index.d.ts:285



---
url: /api/reactlynx-testing-library/Function.computeHeadingLevel.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / computeHeadingLevel

# Function: computeHeadingLevel()

```ts
function computeHeadingLevel(element: Element): number | undefined
```

## Parameters

| Parameter | Type      |
| --------- | --------- |
| `element` | `Element` |

## Returns

`number` | `undefined`

## Defined in

index.d.ts:287



---
url: /api/reactlynx-testing-library/Function.configure.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / configure

# Function: configure()

```ts
function configure(configDelta: ConfigFn | Partial<Config>): void
```

## Parameters

| Parameter     | Type                                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `configDelta` | [`ConfigFn`](/api/reactlynx-testing-library/Interface.ConfigFn.md) \| `Partial`\<[`Config`](/api/reactlynx-testing-library/Interface.Config.md)> |

## Returns

`void`

## Defined in

index.d.ts:314



---
url: /api/reactlynx-testing-library/Function.createEvent.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / createEvent

# Function: createEvent()

```ts
function createEvent(
   eventName: string, 
   node: any, 
   init?: object, 
   options?: object): Event
```

## Parameters

| Parameter              | Type     |
| ---------------------- | -------- |
| `eventName`            | `string` |
| `node`                 | `any`    |
| `init`?                | `object` |
| `options`?             | `object` |
| `options.defaultInit`? | `object` |
| `options.EventType`?   | `string` |

## Returns

`Event`

## Defined in

index.d.ts:316



---
url: /api/reactlynx-testing-library/Function.findAllByAltText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByAltText

# Function: findAllByAltText()

```ts
function findAllByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:454



---
url: /api/reactlynx-testing-library/Function.findAllByDisplayValue.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByDisplayValue

# Function: findAllByDisplayValue()

```ts
function findAllByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:465



---
url: /api/reactlynx-testing-library/Function.findAllByLabelText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByLabelText

# Function: findAllByLabelText()

```ts
function findAllByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindAllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByText`](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)\<`T`>>

## Defined in

index.d.ts:469



---
url: /api/reactlynx-testing-library/Function.findAllByPlaceholderText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByPlaceholderText

# Function: findAllByPlaceholderText()

```ts
function findAllByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:473



---
url: /api/reactlynx-testing-library/Function.findAllByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByRole

# Function: findAllByRole()

```ts
function findAllByRole<T>(...args: [HTMLElement, any, ByRoleOptions, waitForOptions]): ReturnType<FindAllByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByRole`](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md)\<`T`>>

## Defined in

index.d.ts:484



---
url: /api/reactlynx-testing-library/Function.findAllByTestId.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByTestId

# Function: findAllByTestId()

```ts
function findAllByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:488



---
url: /api/reactlynx-testing-library/Function.findAllByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByText

# Function: findAllByText()

```ts
function findAllByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindAllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByText`](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)\<`T`>>

## Defined in

index.d.ts:499



---
url: /api/reactlynx-testing-library/Function.findAllByTitle.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByTitle

# Function: findAllByTitle()

```ts
function findAllByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:503



---
url: /api/reactlynx-testing-library/Function.findByAltText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByAltText

# Function: findByAltText()

```ts
function findByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:512



---
url: /api/reactlynx-testing-library/Function.findByDisplayValue.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByDisplayValue

# Function: findByDisplayValue()

```ts
function findByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:523



---
url: /api/reactlynx-testing-library/Function.findByLabelText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByLabelText

# Function: findByLabelText()

```ts
function findByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByText`](/api/reactlynx-testing-library/TypeAlias.FindByText.md)\<`T`>>

## Defined in

index.d.ts:527



---
url: /api/reactlynx-testing-library/Function.findByPlaceholderText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByPlaceholderText

# Function: findByPlaceholderText()

```ts
function findByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:531



---
url: /api/reactlynx-testing-library/Function.findByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByRole

# Function: findByRole()

```ts
function findByRole<T>(...args: [HTMLElement, any, ByRoleOptions, waitForOptions]): ReturnType<FindByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByRole`](/api/reactlynx-testing-library/TypeAlias.FindByRole.md)\<`T`>>

## Defined in

index.d.ts:542



---
url: /api/reactlynx-testing-library/Function.findByTestId.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByTestId

# Function: findByTestId()

```ts
function findByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:546



---
url: /api/reactlynx-testing-library/Function.findByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByText

# Function: findByText()

```ts
function findByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByText`](/api/reactlynx-testing-library/TypeAlias.FindByText.md)\<`T`>>

## Defined in

index.d.ts:557



---
url: /api/reactlynx-testing-library/Function.findByTitle.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByTitle

# Function: findByTitle()

```ts
function findByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:561



---
url: /api/reactlynx-testing-library/Function.fireEvent.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / fireEvent

# Function: fireEvent()

```ts
function fireEvent(element: any, event: Event): boolean
```

## Parameters

| Parameter | Type    |
| --------- | ------- |
| `element` | `any`   |
| `event`   | `Event` |

## Returns

`boolean`

## Defined in

index.d.ts:565



---
url: /api/reactlynx-testing-library/Function.getAllByAltText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByAltText

# Function: getAllByAltText()

```ts
function getAllByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:584



---
url: /api/reactlynx-testing-library/Function.getAllByDisplayValue.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByDisplayValue

# Function: getAllByDisplayValue()

```ts
function getAllByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:588



---
url: /api/reactlynx-testing-library/Function.getAllByLabelText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByLabelText

# Function: getAllByLabelText()

```ts
function getAllByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:592



---
url: /api/reactlynx-testing-library/Function.getAllByPlaceholderText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByPlaceholderText

# Function: getAllByPlaceholderText()

```ts
function getAllByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:596



---
url: /api/reactlynx-testing-library/Function.getAllByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByRole

# Function: getAllByRole()

```ts
function getAllByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<AllByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`AllByRole`](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)\<`T`>>

## Defined in

index.d.ts:600



---
url: /api/reactlynx-testing-library/Function.getAllByTestId.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByTestId

# Function: getAllByTestId()

```ts
function getAllByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:604



---
url: /api/reactlynx-testing-library/Function.getAllByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByText

# Function: getAllByText()

```ts
function getAllByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:608



---
url: /api/reactlynx-testing-library/Function.getAllByTitle.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByTitle

# Function: getAllByTitle()

```ts
function getAllByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:612



---
url: /api/reactlynx-testing-library/Function.getByAltText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByAltText

# Function: getByAltText()

```ts
function getByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:618



---
url: /api/reactlynx-testing-library/Function.getByDisplayValue.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByDisplayValue

# Function: getByDisplayValue()

```ts
function getByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:628



---
url: /api/reactlynx-testing-library/Function.getByLabelText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByLabelText

# Function: getByLabelText()

```ts
function getByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<GetByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByText`](/api/reactlynx-testing-library/TypeAlias.GetByText.md)\<`T`>>

## Defined in

index.d.ts:632



---
url: /api/reactlynx-testing-library/Function.getByPlaceholderText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByPlaceholderText

# Function: getByPlaceholderText()

```ts
function getByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:636



---
url: /api/reactlynx-testing-library/Function.getByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByRole

# Function: getByRole()

```ts
function getByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<GetByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`GetByRole`](/api/reactlynx-testing-library/TypeAlias.GetByRole.md)\<`T`>>

## Defined in

index.d.ts:646



---
url: /api/reactlynx-testing-library/Function.getByTestId.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByTestId

# Function: getByTestId()

```ts
function getByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:650



---
url: /api/reactlynx-testing-library/Function.getByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByText

# Function: getByText()

```ts
function getByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<GetByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByText`](/api/reactlynx-testing-library/TypeAlias.GetByText.md)\<`T`>>

## Defined in

index.d.ts:660



---
url: /api/reactlynx-testing-library/Function.getByTitle.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByTitle

# Function: getByTitle()

```ts
function getByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:664



---
url: /api/reactlynx-testing-library/Function.getConfig.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getConfig

# Function: getConfig()

```ts
function getConfig(): Config
```

## Returns

[`Config`](/api/reactlynx-testing-library/Interface.Config.md)

## Defined in

index.d.ts:668



---
url: /api/reactlynx-testing-library/Function.getDefaultNormalizer.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getDefaultNormalizer

# Function: getDefaultNormalizer()

```ts
function getDefaultNormalizer(options?: DefaultNormalizerOptions): NormalizerFn
```

## Parameters

| Parameter  | Type                                                                                               |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `options`? | [`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md) |

## Returns

[`NormalizerFn`](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md)

## Defined in

index.d.ts:670



---
url: /api/reactlynx-testing-library/Function.getElementError.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getElementError

# Function: getElementError()

```ts
function getElementError(message: null | string, container: HTMLElement): Error
```

## Parameters

| Parameter   | Type               |
| ----------- | ------------------ |
| `message`   | `null` \| `string` |
| `container` | `HTMLElement`      |

## Returns

`Error`

## Defined in

index.d.ts:674



---
url: /api/reactlynx-testing-library/Function.getNodeText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getNodeText

# Function: getNodeText()

```ts
function getNodeText(node: HTMLElement): string
```

## Parameters

| Parameter | Type          |
| --------- | ------------- |
| `node`    | `HTMLElement` |

## Returns

`string`

## Defined in

index.d.ts:684



---
url: /api/reactlynx-testing-library/Function.getQueriesForElement.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getQueriesForElement

# Function: getQueriesForElement()

```ts
function getQueriesForElement<QueriesToBind, T>(element: HTMLElement, queriesToBind?: T): BoundFunctions<T>
```

## Type Parameters

| Type Parameter                                                                             | Default type                                                              |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `QueriesToBind` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |
| `T` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md)             | `QueriesToBind`                                                           |

## Parameters

| Parameter        | Type          |
| ---------------- | ------------- |
| `element`        | `HTMLElement` |
| `queriesToBind`? | `T`           |

## Returns

[`BoundFunctions`](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md)\<`T`>

## Defined in

index.d.ts:686



---
url: /api/reactlynx-testing-library/Function.getRoles.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getRoles

# Function: getRoles()

```ts
function getRoles(container: HTMLElement): object
```

## Parameters

| Parameter   | Type          |
| ----------- | ------------- |
| `container` | `HTMLElement` |

## Returns

`object`

## Defined in

index.d.ts:692



---
url: /api/reactlynx-testing-library/Function.getSuggestedQuery.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getSuggestedQuery

# Function: getSuggestedQuery()

```ts
function getSuggestedQuery(
   element: HTMLElement, 
   variant?: Variant, 
   method?: Method): Suggestion | undefined
```

## Parameters

| Parameter  | Type                                                             |
| ---------- | ---------------------------------------------------------------- |
| `element`  | `HTMLElement`                                                    |
| `variant`? | [`Variant`](/api/reactlynx-testing-library/TypeAlias.Variant.md) |
| `method`?  | [`Method`](/api/reactlynx-testing-library/TypeAlias.Method.md)   |

## Returns

[`Suggestion`](/api/reactlynx-testing-library/Interface.Suggestion.md) | `undefined`

## Defined in

index.d.ts:696



---
url: /api/reactlynx-testing-library/Function.isInaccessible.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / isInaccessible

# Function: isInaccessible()

```ts
function isInaccessible(element: Element): boolean
```

[https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible](https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible)

## Parameters

| Parameter | Type      |
| --------- | --------- |
| `element` | `Element` |

## Returns

`boolean`

## Defined in

index.d.ts:773



---
url: /api/reactlynx-testing-library/Function.logDOM.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / logDOM

# Function: logDOM()

```ts
function logDOM(
   dom?: any, 
   maxLength?: number, 
   options?: PrettyDOMOptions): void
```

## Parameters

| Parameter    | Type                                                                               |
| ------------ | ---------------------------------------------------------------------------------- |
| `dom`?       | `any`                                                                              |
| `maxLength`? | `number`                                                                           |
| `options`?   | [`PrettyDOMOptions`](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md) |

## Returns

`void`

## Defined in

index.d.ts:775



---
url: /api/reactlynx-testing-library/Function.logRoles.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / logRoles

# Function: logRoles()

```ts
function logRoles(container: HTMLElement, options?: LogRolesOptions): string
```

## Parameters

| Parameter   | Type                                                                             |
| ----------- | -------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                    |
| `options`?  | [`LogRolesOptions`](/api/reactlynx-testing-library/Interface.LogRolesOptions.md) |

## Returns

`string`

## Defined in

index.d.ts:781



---
url: /api/reactlynx-testing-library/Function.prettyDOM.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / prettyDOM

# Function: prettyDOM()

```ts
function prettyDOM(
   dom?: any, 
   maxLength?: number, 
   options?: PrettyDOMOptions): string | false
```

## Parameters

| Parameter    | Type                                                                               |
| ------------ | ---------------------------------------------------------------------------------- |
| `dom`?       | `any`                                                                              |
| `maxLength`? | `number`                                                                           |
| `options`?   | [`PrettyDOMOptions`](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md) |

## Returns

`string` | `false`

## Defined in

index.d.ts:967



---
url: /api/reactlynx-testing-library/Function.queryAllByAltText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByAltText

# Function: queryAllByAltText()

```ts
function queryAllByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1068



---
url: /api/reactlynx-testing-library/Function.queryAllByAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByAttribute

# Function: queryAllByAttribute()

```ts
function queryAllByAttribute(
   attribute: string, 
   container: HTMLElement, 
   id: Matcher, 
   options?: MatcherOptions): HTMLElement[]
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`HTMLElement`\[]

## Defined in

index.d.ts:1072



---
url: /api/reactlynx-testing-library/Function.queryAllByDisplayValue.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByDisplayValue

# Function: queryAllByDisplayValue()

```ts
function queryAllByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1074



---
url: /api/reactlynx-testing-library/Function.queryAllByLabelText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByLabelText

# Function: queryAllByLabelText()

```ts
function queryAllByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:1078



---
url: /api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByPlaceholderText

# Function: queryAllByPlaceholderText()

```ts
function queryAllByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1082



---
url: /api/reactlynx-testing-library/Function.queryAllByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByRole

# Function: queryAllByRole()

```ts
function queryAllByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<AllByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`AllByRole`](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)\<`T`>>

## Defined in

index.d.ts:1086



---
url: /api/reactlynx-testing-library/Function.queryAllByTestId.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByTestId

# Function: queryAllByTestId()

```ts
function queryAllByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1090



---
url: /api/reactlynx-testing-library/Function.queryAllByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByText

# Function: queryAllByText()

```ts
function queryAllByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:1094



---
url: /api/reactlynx-testing-library/Function.queryAllByTitle.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByTitle

# Function: queryAllByTitle()

```ts
function queryAllByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1098



---
url: /api/reactlynx-testing-library/Function.queryByAltText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByAltText

# Function: queryByAltText()

```ts
function queryByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1109



---
url: /api/reactlynx-testing-library/Function.queryByAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByAttribute

# Function: queryByAttribute()

```ts
function queryByAttribute(
   attribute: string, 
   container: HTMLElement, 
   id: Matcher, 
   options?: MatcherOptions): any
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`any`

## Defined in

index.d.ts:1120



---
url: /api/reactlynx-testing-library/Function.queryByDisplayValue.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByDisplayValue

# Function: queryByDisplayValue()

```ts
function queryByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1128



---
url: /api/reactlynx-testing-library/Function.queryByLabelText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByLabelText

# Function: queryByLabelText()

```ts
function queryByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<QueryByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByText`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)\<`T`>>

## Defined in

index.d.ts:1132



---
url: /api/reactlynx-testing-library/Function.queryByPlaceholderText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByPlaceholderText

# Function: queryByPlaceholderText()

```ts
function queryByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1136



---
url: /api/reactlynx-testing-library/Function.queryByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByRole

# Function: queryByRole()

```ts
function queryByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<QueryByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`QueryByRole`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md)\<`T`>>

## Defined in

index.d.ts:1146



---
url: /api/reactlynx-testing-library/Function.queryByTestId.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByTestId

# Function: queryByTestId()

```ts
function queryByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1150



---
url: /api/reactlynx-testing-library/Function.queryByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByText

# Function: queryByText()

```ts
function queryByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<QueryByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByText`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)\<`T`>>

## Defined in

index.d.ts:1160



---
url: /api/reactlynx-testing-library/Function.queryByTitle.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByTitle

# Function: queryByTitle()

```ts
function queryByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1164



---
url: /api/reactlynx-testing-library/Function.render.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / render

# Function: render()

```ts
function render<Q>(ui: ComponentChild, options?: RenderOptions<Q>): RenderResult<Q>
```

Render into the page. It should be used with cleanup.

## Type Parameters

| Type Parameter                                                                 |
| ------------------------------------------------------------------------------ |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) |

## Parameters

| Parameter  | Type                                                                               |
| ---------- | ---------------------------------------------------------------------------------- |
| `ui`       | `ComponentChild`                                                                   |
| `options`? | [`RenderOptions`](/api/reactlynx-testing-library/Interface.RenderOptions.md)\<`Q`> |

## Returns

[`RenderResult`](/api/reactlynx-testing-library/TypeAlias.RenderResult.md)\<`Q`>

## Example

```ts
import { render} from '@lynx-js/react/testing-library'

const WrapperComponent = ({ children }) => (
    <view data-testid='wrapper'>{children}</view>
);
const Comp = () => {
  return <view data-testid='inner' style="background-color: yellow;" />;
};
const { container, getByTestId } = render(<Comp />, {
  wrapper: WrapperComponent,
});
expect(getByTestId('wrapper')).toBeInTheDocument();
expect(container.firstChild).toMatchInlineSnapshot(`
  <view
    data-testid="wrapper"
  >
    <view
      data-testid="inner"
      style="background-color: yellow;"
    />
  </view>
`);
```

## Defined in

index.d.ts:1234



---
url: /api/reactlynx-testing-library/Function.renderHook.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / renderHook

# Function: renderHook()

```ts
function renderHook<Result, Props>(render: (initialProps: Props) => Result, options?: RenderHookOptions<Props>): RenderHookResult<Result, Props>
```

Allows you to render a hook within a test React component without having to
create that component yourself.

## Type Parameters

| Type Parameter |
| -------------- |
| `Result`       |
| `Props`        |

## Parameters

| Parameter  | Type                                                                                           |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `render`   | (`initialProps`: `Props`) => `Result`                                                          |
| `options`? | [`RenderHookOptions`](/api/reactlynx-testing-library/Interface.RenderHookOptions.md)\<`Props`> |

## Returns

[`RenderHookResult`](/api/reactlynx-testing-library/Interface.RenderHookResult.md)\<`Result`, `Props`>

## Example

```ts
import { renderHook } from '@lynx-js/react/testing-library'

const Context = createContext('default');
function Wrapper({ children }) {
  return <Context.Provider value='provided'>{children}</Context.Provider>;
}
const { result } = renderHook(
  () => {
    return useContext(Context);
  },
  {
    wrapper: Wrapper,
  },
);

expect(result.current).toEqual('provided');
```

## Defined in

index.d.ts:1266



---
url: /api/reactlynx-testing-library/Function.waitFor.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitFor

# Function: waitFor()

```ts
function waitFor<T>(callback: () => T | Promise<T>, options?: waitForOptions): Promise<T>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter  | Type                                                                           |
| ---------- | ------------------------------------------------------------------------------ |
| `callback` | () => `T` \| `Promise`\<`T`>                                                   |
| `options`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:1473



---
url: /api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitForElementToBeRemoved

# Function: waitForElementToBeRemoved()

```ts
function waitForElementToBeRemoved<T>(callback: T | () => T, options?: waitForOptions): Promise<void>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter  | Type                                                                           |
| ---------- | ------------------------------------------------------------------------------ |
| `callback` | `T` \| () => `T`                                                               |
| `options`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`void`>

## Defined in

index.d.ts:1478



---
url: /api/reactlynx-testing-library/Function.waitSchedule.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitSchedule

# Function: waitSchedule()

```ts
function waitSchedule(): Promise<void>
```

Wait for the next event loop.

It will be useful when you want to wait for the next event loop to finish.

## Returns

`Promise`\<`void`>

## Defined in

index.d.ts:1498



---
url: /api/reactlynx-testing-library/Function.within.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / within

# Function: within()

```ts
function within<QueriesToBind, T>(element: HTMLElement, queriesToBind?: T): BoundFunctions<T>
```

## Type Parameters

| Type Parameter                                                                             | Default type                                                              |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `QueriesToBind` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |
| `T` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md)             | `QueriesToBind`                                                           |

## Parameters

| Parameter        | Type          |
| ---------------- | ------------- |
| `element`        | `HTMLElement` |
| `queriesToBind`? | `T`           |

## Returns

[`BoundFunctions`](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md)\<`T`>

## Defined in

index.d.ts:1500



---
url: /api/reactlynx-testing-library/Interface.ByRoleOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ByRoleOptions

# Interface: ByRoleOptions

## Properties

### busy?

```ts
optional busy: boolean;
```

If true only includes elements in the query set that are marked as
busy in the accessibility tree, i.e., `aria-busy="true"`

#### Defined in

index.d.ts:227

***

### checked?

```ts
optional checked: boolean;
```

If true only includes elements in the query set that are marked as
checked in the accessibility tree, i.e., `aria-checked="true"`

#### Defined in

index.d.ts:232

***

### current?

```ts
optional current: string | boolean;
```

Filters elements by their `aria-current` state. `true` and `false` match `aria-current="true"` and `aria-current="false"` (as well as a missing `aria-current` attribute) respectively.

#### Defined in

index.d.ts:241

***

### description?

```ts
optional description: string | RegExp | (accessibleDescription: string, element: Element) => boolean;
```

Only considers elements with the specified accessible description.

#### Defined in

index.d.ts:274

***

### expanded?

```ts
optional expanded: boolean;
```

If true only includes elements in the query set that are marked as
expanded in the accessibility tree, i.e., `aria-expanded="true"`

#### Defined in

index.d.ts:246

***

### hidden?

```ts
optional hidden: boolean;
```

If true includes elements in the query set that are usually excluded from
the accessibility tree. `role="none"` or `role="presentation"` are included
in either case.

#### Defined in

index.d.ts:217

***

### level?

```ts
optional level: number;
```

Includes elements with the `"heading"` role matching the indicated level,
either by the semantic HTML heading elements `<h1>-<h6>` or matching
the `aria-level` attribute.

#### Defined in

index.d.ts:252

***

### name?

```ts
optional name: string | RegExp | (accessibleName: string, element: Element) => boolean;
```

Only considers elements with the specified accessible name.

#### Defined in

index.d.ts:267

***

### pressed?

```ts
optional pressed: boolean;
```

If true only includes elements in the query set that are marked as
pressed in the accessibility tree, i.e., `aria-pressed="true"`

#### Defined in

index.d.ts:237

***

### queryFallbacks?

```ts
optional queryFallbacks: boolean;
```

Includes every role used in the `role` attribute
For example \*ByRole('progressbar', \{queryFallbacks: true})` will find <div role="meter progressbar">`.

#### Defined in

index.d.ts:263

***

### selected?

```ts
optional selected: boolean;
```

If true only includes elements in the query set that are marked as
selected in the accessibility tree, i.e., `aria-selected="true"`

#### Defined in

index.d.ts:222

***

### suggest?

```ts
optional suggest: boolean;
```

suppress suggestions for a specific query

#### Defined in

index.d.ts:211

***

### value?

```ts
optional value: object;
```

#### max?

```ts
optional max: number;
```

#### min?

```ts
optional min: number;
```

#### now?

```ts
optional now: number;
```

#### text?

```ts
optional text: Matcher;
```

#### Defined in

index.d.ts:253



---
url: /api/reactlynx-testing-library/Interface.Config.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Config

# Interface: Config

## Properties

### asyncUtilTimeout

```ts
asyncUtilTimeout: number;
```

#### Defined in

index.d.ts:300

***

### computedStyleSupportsPseudoElements

```ts
computedStyleSupportsPseudoElements: boolean;
```

#### Defined in

index.d.ts:301

***

### defaultHidden

```ts
defaultHidden: boolean;
```

#### Defined in

index.d.ts:302

***

### defaultIgnore

```ts
defaultIgnore: string;
```

default value for the `ignore` option in `ByText` queries

#### Defined in

index.d.ts:304

***

### getElementError()

```ts
getElementError: (message: null | string, container: Element) => Error;
```

#### Parameters

| Parameter   | Type               |
| ----------- | ------------------ |
| `message`   | `null` \| `string` |
| `container` | `Element`          |

#### Returns

`Error`

#### Defined in

index.d.ts:307

***

### showOriginalStackTrace

```ts
showOriginalStackTrace: boolean;
```

#### Defined in

index.d.ts:305

***

### testIdAttribute

```ts
testIdAttribute: string;
```

#### Defined in

index.d.ts:290

***

### throwSuggestions

```ts
throwSuggestions: boolean;
```

#### Defined in

index.d.ts:306

## Methods

### asyncWrapper()

```ts
asyncWrapper(cb: (...args: any[]) => any): Promise<any>
```

#### Parameters

| Parameter | Type                           |
| --------- | ------------------------------ |
| `cb`      | (...`args`: `any`\[]) => `any` |

#### Returns

`Promise`\<`any`>

#### Defined in

index.d.ts:297

***

### eventWrapper()

```ts
eventWrapper(cb: (...args: any[]) => any): void
```

#### Parameters

| Parameter | Type                           |
| --------- | ------------------------------ |
| `cb`      | (...`args`: `any`\[]) => `any` |

#### Returns

`void`

#### Defined in

index.d.ts:299

***

### unstable\_advanceTimersWrapper()

```ts
unstable_advanceTimersWrapper(cb: (...args: unknown[]) => unknown): unknown
```

WARNING: `unstable` prefix means this API may change in patch and minor releases.

#### Parameters

| Parameter | Type                                   | Description |
| --------- | -------------------------------------- | ----------- |
| `cb`      | (...`args`: `unknown`\[]) => `unknown` |             |

#### Returns

`unknown`

#### Defined in

index.d.ts:295



---
url: /api/reactlynx-testing-library/Interface.ConfigFn.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ConfigFn

# Interface: ConfigFn()

```ts
interface ConfigFn(existingConfig: Config): Partial<Config>
```

## Parameters

| Parameter        | Type                                                           |
| ---------------- | -------------------------------------------------------------- |
| `existingConfig` | [`Config`](/api/reactlynx-testing-library/Interface.Config.md) |

## Returns

`Partial`\<[`Config`](/api/reactlynx-testing-library/Interface.Config.md)>

## Defined in

index.d.ts:311



---
url: /api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / DefaultNormalizerOptions

# Interface: DefaultNormalizerOptions

## Extended by

- [`NormalizerOptions`](/api/reactlynx-testing-library/Interface.NormalizerOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

#### Defined in

index.d.ts:334

***

### trim?

```ts
optional trim: boolean;
```

#### Defined in

index.d.ts:333



---
url: /api/reactlynx-testing-library/Interface.LogRolesOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / LogRolesOptions

# Interface: LogRolesOptions

## Properties

### hidden?

```ts
optional hidden: boolean;
```

#### Defined in

index.d.ts:787



---
url: /api/reactlynx-testing-library/Interface.MatcherOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / MatcherOptions

# Interface: MatcherOptions

## Extended by

- [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Defined in

index.d.ts:932

***

### exact?

```ts
optional exact: boolean;
```

#### Defined in

index.d.ts:928

***

### normalizer?

```ts
optional normalizer: NormalizerFn;
```

#### Defined in

index.d.ts:933

***

### suggest?

```ts
optional suggest: boolean;
```

suppress suggestions for a specific query

#### Defined in

index.d.ts:935

***

### trim?

```ts
optional trim: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Defined in

index.d.ts:930



---
url: /api/reactlynx-testing-library/Interface.NormalizerOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / NormalizerOptions

# Interface: NormalizerOptions

## Extends

- [`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

#### Inherited from

[`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md).[`collapseWhitespace`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md#collapsewhitespace)

#### Defined in

index.d.ts:334

***

### normalizer?

```ts
optional normalizer: NormalizerFn;
```

#### Defined in

index.d.ts:959

***

### trim?

```ts
optional trim: boolean;
```

#### Inherited from

[`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md).[`trim`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md#trim)

#### Defined in

index.d.ts:333



---
url: /api/reactlynx-testing-library/Interface.PrettyDOMOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / PrettyDOMOptions

# Interface: PrettyDOMOptions

## Extends

- [`prettyFormat`](/api/reactlynx-testing-library/Variable.prettyFormat.md)

## Properties

### filterNode()?

```ts
optional filterNode: (node: Node) => boolean;
```

Given a `Node` return `false` if you wish to ignore that node in the output.
By default, ignores `<style />`, `<script />` and comment nodes.

#### Parameters

| Parameter | Type   |
| --------- | ------ |
| `node`    | `Node` |

#### Returns

`boolean`

#### Defined in

index.d.ts:978



---
url: /api/reactlynx-testing-library/Interface.Queries.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Queries

# Interface: Queries

## Indexable

\[`T`: `string`]: [`Query`](/api/reactlynx-testing-library/TypeAlias.Query.md)



---
url: /api/reactlynx-testing-library/Interface.QueryOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryOptions

# Interface: QueryOptions

## Indexable

\[`key`: `string`]: `RegExp` | `boolean`



---
url: /api/reactlynx-testing-library/Interface.RenderHookOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderHookOptions

# Interface: RenderHookOptions\<Props>

The options for [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)

## Type Parameters

| Type Parameter |
| -------------- |
| `Props`        |

## Properties

### initialProps?

```ts
optional initialProps: Props;
```

The argument passed to the renderHook callback. Can be useful if you plan
to use the rerender utility to change the values passed to your hook.

#### Defined in

index.d.ts:1281

***

### wrapper?

```ts
optional wrapper: any;
```

Pass a React Component as the wrapper option to have it rendered around the inner element. This is most useful for creating
reusable custom render functions for common data providers. See setup for examples.

#### Example

```ts
import { renderHook } from '@lynx-js/react/testing-library'
import { ThemeProvider } from 'my-ui-lib'
import { TranslationProvider } from 'my-i18n-lib'
import defaultStrings from 'i18n/en-x-default'

const AllTheProviders = ({children}) => {
  return (
    <ThemeProvider theme="light">
      <TranslationProvider messages={defaultStrings}>
        {children}
      </TranslationProvider>
    </ThemeProvider>
  )
}

const customRenderHook = (ui, options) =>
  renderHook(ui, { wrapper: AllTheProviders, ...options })

// re-export everything
export * from '@lynx-js/react/testing-library'

// override renderHook method
export { customRender as renderHook }
```

#### Defined in

index.d.ts:1314



---
url: /api/reactlynx-testing-library/Interface.RenderHookResult.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderHookResult

# Interface: RenderHookResult\<Result, Props>

The result of [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)

## Type Parameters

| Type Parameter |
| -------------- |
| `Result`       |
| `Props`        |

## Properties

### rerender()

```ts
rerender: (props?: Props) => void;
```

Triggers a re-render. The props will be passed to your renderHook callback.

#### Parameters

| Parameter | Type    |
| --------- | ------- |
| `props`?  | `Props` |

#### Returns

`void`

#### Defined in

index.d.ts:1327

***

### result

```ts
result: object;
```

This is a stable reference to the latest value returned by your renderHook
callback

#### current

```ts
current: Result;
```

The value returned by your renderHook callback

#### Defined in

index.d.ts:1332

***

### unmount()

```ts
unmount: () => void;
```

Unmounts the test component. This is useful for when you need to test
any cleanup your useEffects have.

#### Returns

`void`

#### Defined in

index.d.ts:1342



---
url: /api/reactlynx-testing-library/Interface.RenderOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderOptions

# Interface: RenderOptions\<Q>

The options for [render](/api/reactlynx-testing-library/Function.render.md).

## Type Parameters

| Type Parameter                                                                 | Default type                                                              |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |

## Properties

### enableBackgroundThread?

```ts
optional enableBackgroundThread: boolean;
```

Render your component in the background thread or not.

Note that all user code in the top level will be executed in the background thread by default. (eg. `__BACKGROUND__` is `true` in the top level)

#### Default Value

```ts
true
```

#### Defined in

index.d.ts:1416

***

### enableMainThread?

```ts
optional enableMainThread: boolean;
```

Render your component in the main thread or not.

It is recommended to use this option only when you need to test the [IFR](/guide/interaction/ifr.md) behavior.

#### Default Value

```ts
false
```

#### Defined in

index.d.ts:1408

***

### queries?

```ts
optional queries: Q;
```

Queries to bind. Overrides the default set from DOM Testing Library unless merged.

#### Example

```ts
// Example, a function to traverse table contents
import * as tableQueries from 'my-table-query-library'
import { queries } from '@lynx-js/react/testing-library'

const { getByRowColumn, getByText } = render(<MyTable />, {
  queries: {...queries, ...tableQueries},
})

```

#### Defined in

index.d.ts:1367

***

### wrapper?

```ts
optional wrapper: any;
```

Pass a React Component as the wrapper option to have it rendered around the inner element. This is most useful for creating
reusable custom render functions for common data providers. See setup for examples.

#### Example

```ts
import { render } from '@lynx-js/react/testing-library'
import { ThemeProvider } from 'my-ui-lib'
import { TranslationProvider } from 'my-i18n-lib'
import defaultStrings from 'i18n/en-x-default'

const AllTheProviders = ({children}) => {
  return (
    <ThemeProvider theme="light">
      <TranslationProvider messages={defaultStrings}>
        {children}
      </TranslationProvider>
    </ThemeProvider>
  )
}

const customRender = (ui, options) =>
  render(ui, { wrapper: AllTheProviders, ...options })

// re-export everything
export * from '@lynx-js/react/testing-library'

// override render method
export { customRender as render }
```

#### Defined in

index.d.ts:1400



---
url: /api/reactlynx-testing-library/Interface.Suggestion.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Suggestion

# Interface: Suggestion

## Properties

### queryArgs

```ts
queryArgs: QueryArgs;
```

#### Defined in

index.d.ts:1459

***

### queryMethod

```ts
queryMethod: string;
```

#### Defined in

index.d.ts:1458

***

### queryName

```ts
queryName: string;
```

#### Defined in

index.d.ts:1457

***

### variant

```ts
variant: string;
```

#### Defined in

index.d.ts:1460

***

### warning?

```ts
optional warning: string;
```

#### Defined in

index.d.ts:1461

## Methods

### toString()

```ts
toString(): string
```

#### Returns

`string`

#### Defined in

index.d.ts:1462



---
url: /api/reactlynx-testing-library/Interface.waitForOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitForOptions

# Interface: waitForOptions

## Properties

### container?

```ts
optional container: any;
```

#### Defined in

index.d.ts:1484

***

### interval?

```ts
optional interval: number;
```

#### Defined in

index.d.ts:1486

***

### mutationObserverOptions?

```ts
optional mutationObserverOptions: any;
```

#### Defined in

index.d.ts:1488

***

### onTimeout()?

```ts
optional onTimeout: (error: Error) => Error;
```

#### Parameters

| Parameter | Type    |
| --------- | ------- |
| `error`   | `Error` |

#### Returns

`Error`

#### Defined in

index.d.ts:1487

***

### timeout?

```ts
optional timeout: number;
```

#### Defined in

index.d.ts:1485



---
url: /api/reactlynx-testing-library/Namespace.queries.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queries

# queries

## Index

### Type Aliases

| Type alias                                                                                         | Description |
| -------------------------------------------------------------------------------------------------- | ----------- |
| [QueryByBoundAttribute](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md) | -           |
| [QueryByRole](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md)                     | -           |
| [QueryByText](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)                     | -           |

## References

### AllByBoundAttribute

Re-exports [AllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)

***

### AllByRole

Re-exports [AllByRole](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)

***

### AllByText

Re-exports [AllByText](/api/reactlynx-testing-library/TypeAlias.AllByText.md)

***

### ByRoleOptions

Re-exports [ByRoleOptions](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)

***

### findAllByAltText

Re-exports [findAllByAltText](/api/reactlynx-testing-library/Function.findAllByAltText.md)

***

### FindAllByBoundAttribute

Re-exports [FindAllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)

***

### findAllByDisplayValue

Re-exports [findAllByDisplayValue](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md)

***

### findAllByLabelText

Re-exports [findAllByLabelText](/api/reactlynx-testing-library/Function.findAllByLabelText.md)

***

### findAllByPlaceholderText

Re-exports [findAllByPlaceholderText](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md)

***

### findAllByRole

Re-exports [findAllByRole](/api/reactlynx-testing-library/Function.findAllByRole.md)

***

### FindAllByRole

Re-exports [FindAllByRole](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md)

***

### findAllByTestId

Re-exports [findAllByTestId](/api/reactlynx-testing-library/Function.findAllByTestId.md)

***

### findAllByText

Re-exports [findAllByText](/api/reactlynx-testing-library/Function.findAllByText.md)

***

### FindAllByText

Re-exports [FindAllByText](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)

***

### findAllByTitle

Re-exports [findAllByTitle](/api/reactlynx-testing-library/Function.findAllByTitle.md)

***

### findByAltText

Re-exports [findByAltText](/api/reactlynx-testing-library/Function.findByAltText.md)

***

### FindByBoundAttribute

Re-exports [FindByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)

***

### findByDisplayValue

Re-exports [findByDisplayValue](/api/reactlynx-testing-library/Function.findByDisplayValue.md)

***

### findByLabelText

Re-exports [findByLabelText](/api/reactlynx-testing-library/Function.findByLabelText.md)

***

### findByPlaceholderText

Re-exports [findByPlaceholderText](/api/reactlynx-testing-library/Function.findByPlaceholderText.md)

***

### findByRole

Re-exports [findByRole](/api/reactlynx-testing-library/Function.findByRole.md)

***

### FindByRole

Re-exports [FindByRole](/api/reactlynx-testing-library/TypeAlias.FindByRole.md)

***

### findByTestId

Re-exports [findByTestId](/api/reactlynx-testing-library/Function.findByTestId.md)

***

### findByText

Re-exports [findByText](/api/reactlynx-testing-library/Function.findByText.md)

***

### FindByText

Re-exports [FindByText](/api/reactlynx-testing-library/TypeAlias.FindByText.md)

***

### findByTitle

Re-exports [findByTitle](/api/reactlynx-testing-library/Function.findByTitle.md)

***

### getAllByAltText

Re-exports [getAllByAltText](/api/reactlynx-testing-library/Function.getAllByAltText.md)

***

### getAllByDisplayValue

Re-exports [getAllByDisplayValue](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md)

***

### getAllByLabelText

Re-exports [getAllByLabelText](/api/reactlynx-testing-library/Function.getAllByLabelText.md)

***

### getAllByPlaceholderText

Re-exports [getAllByPlaceholderText](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md)

***

### getAllByRole

Re-exports [getAllByRole](/api/reactlynx-testing-library/Function.getAllByRole.md)

***

### getAllByTestId

Re-exports [getAllByTestId](/api/reactlynx-testing-library/Function.getAllByTestId.md)

***

### getAllByText

Re-exports [getAllByText](/api/reactlynx-testing-library/Function.getAllByText.md)

***

### getAllByTitle

Re-exports [getAllByTitle](/api/reactlynx-testing-library/Function.getAllByTitle.md)

***

### getByAltText

Re-exports [getByAltText](/api/reactlynx-testing-library/Function.getByAltText.md)

***

### GetByBoundAttribute

Re-exports [GetByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)

***

### getByDisplayValue

Re-exports [getByDisplayValue](/api/reactlynx-testing-library/Function.getByDisplayValue.md)

***

### getByLabelText

Re-exports [getByLabelText](/api/reactlynx-testing-library/Function.getByLabelText.md)

***

### getByPlaceholderText

Re-exports [getByPlaceholderText](/api/reactlynx-testing-library/Function.getByPlaceholderText.md)

***

### getByRole

Re-exports [getByRole](/api/reactlynx-testing-library/Function.getByRole.md)

***

### GetByRole

Re-exports [GetByRole](/api/reactlynx-testing-library/TypeAlias.GetByRole.md)

***

### getByTestId

Re-exports [getByTestId](/api/reactlynx-testing-library/Function.getByTestId.md)

***

### getByText

Re-exports [getByText](/api/reactlynx-testing-library/Function.getByText.md)

***

### GetByText

Re-exports [GetByText](/api/reactlynx-testing-library/TypeAlias.GetByText.md)

***

### getByTitle

Re-exports [getByTitle](/api/reactlynx-testing-library/Function.getByTitle.md)

***

### queryAllByAltText

Re-exports [queryAllByAltText](/api/reactlynx-testing-library/Function.queryAllByAltText.md)

***

### queryAllByDisplayValue

Re-exports [queryAllByDisplayValue](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md)

***

### queryAllByLabelText

Re-exports [queryAllByLabelText](/api/reactlynx-testing-library/Function.queryAllByLabelText.md)

***

### queryAllByPlaceholderText

Re-exports [queryAllByPlaceholderText](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md)

***

### queryAllByRole

Re-exports [queryAllByRole](/api/reactlynx-testing-library/Function.queryAllByRole.md)

***

### queryAllByTestId

Re-exports [queryAllByTestId](/api/reactlynx-testing-library/Function.queryAllByTestId.md)

***

### queryAllByText

Re-exports [queryAllByText](/api/reactlynx-testing-library/Function.queryAllByText.md)

***

### queryAllByTitle

Re-exports [queryAllByTitle](/api/reactlynx-testing-library/Function.queryAllByTitle.md)

***

### queryByAltText

Re-exports [queryByAltText](/api/reactlynx-testing-library/Function.queryByAltText.md)

***

### queryByDisplayValue

Re-exports [queryByDisplayValue](/api/reactlynx-testing-library/Function.queryByDisplayValue.md)

***

### queryByLabelText

Re-exports [queryByLabelText](/api/reactlynx-testing-library/Function.queryByLabelText.md)

***

### queryByPlaceholderText

Re-exports [queryByPlaceholderText](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md)

***

### queryByRole

Re-exports [queryByRole](/api/reactlynx-testing-library/Function.queryByRole.md)

***

### queryByTestId

Re-exports [queryByTestId](/api/reactlynx-testing-library/Function.queryByTestId.md)

***

### queryByText

Re-exports [queryByText](/api/reactlynx-testing-library/Function.queryByText.md)

***

### queryByTitle

Re-exports [queryByTitle](/api/reactlynx-testing-library/Function.queryByTitle.md)



---
url: /api/reactlynx-testing-library/Namespace.queryHelpers.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryHelpers

# queryHelpers

## Index

### Interfaces

| Interface                                                                                                 | Description |
| --------------------------------------------------------------------------------------------------------- | ----------- |
| [SelectorMatcherOptions](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) | -           |

### Type Aliases

| Type alias                                                                          | Description                                                               |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [QueryMethod](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md) | query methods have a common call signature. Only the return type differs. |
| [WithSuggest](/api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md) | -                                                                         |

## References

### AllByAttribute

Re-exports [AllByAttribute](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md)

***

### buildQueries

Re-exports [buildQueries](/api/reactlynx-testing-library/Function.buildQueries.md)

***

### BuiltQueryMethods

Re-exports [BuiltQueryMethods](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md)

***

### FindAllBy

Re-exports [FindAllBy](/api/reactlynx-testing-library/TypeAlias.FindAllBy.md)

***

### FindBy

Re-exports [FindBy](/api/reactlynx-testing-library/TypeAlias.FindBy.md)

***

### GetAllBy

Re-exports [GetAllBy](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md)

***

### GetBy

Re-exports [GetBy](/api/reactlynx-testing-library/TypeAlias.GetBy.md)

***

### getElementError

Re-exports [getElementError](/api/reactlynx-testing-library/Function.getElementError.md)

***

### GetErrorFunction

Re-exports [GetErrorFunction](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)

***

### queryAllByAttribute

Re-exports [queryAllByAttribute](/api/reactlynx-testing-library/Function.queryAllByAttribute.md)

***

### QueryBy

Re-exports [QueryBy](/api/reactlynx-testing-library/TypeAlias.QueryBy.md)

***

### queryByAttribute

Re-exports [queryByAttribute](/api/reactlynx-testing-library/Function.queryByAttribute.md)

***

### QueryByAttribute

Re-exports [QueryByAttribute](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md)



---
url: /api/reactlynx-testing-library/TypeAlias.AllByAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByAttribute

# Type Alias: AllByAttribute()

```ts
type AllByAttribute: (attribute: string, container: HTMLElement, id: Matcher, options?: MatcherOptions) => HTMLElement[];
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`HTMLElement`\[]

## Defined in

index.d.ts:8



---
url: /api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByBoundAttribute

# Type Alias: AllByBoundAttribute()\<T>

```ts
type AllByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions) => T[];
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`T`\[]

## Defined in

index.d.ts:15



---
url: /api/reactlynx-testing-library/TypeAlias.AllByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByRole

# Type Alias: AllByRole()\<T>

```ts
type AllByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions) => T[];
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                         |
| ----------- | ---------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                |
| `role`      | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md) |
| `options`?  | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md) |

## Returns

`T`\[]

## Defined in

index.d.ts:21



---
url: /api/reactlynx-testing-library/TypeAlias.AllByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByText

# Type Alias: AllByText()\<T>

```ts
type AllByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => T[];
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                                                        |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                                               |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?  | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |

## Returns

`T`\[]

## Defined in

index.d.ts:27



---
url: /api/reactlynx-testing-library/TypeAlias.BoundFunction.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / BoundFunction

# Type Alias: BoundFunction\<T>

```ts
type BoundFunction<T>: T extends (container: HTMLElement, ...args: infer P) => infer R ? (...args: P) => R : never;
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Defined in

index.d.ts:33



---
url: /api/reactlynx-testing-library/TypeAlias.BoundFunctions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / BoundFunctions

# Type Alias: BoundFunctions\<Q>

```ts
type BoundFunctions<Q>: Q extends typeof queries ? object & { [P in keyof Q]: BoundFunction<Q[P]> } : { [P in keyof Q]: BoundFunction<Q[P]> };
```

## Type Parameters

| Type Parameter |
| -------------- |
| `Q`            |

## Defined in

index.d.ts:40



---
url: /api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / BuiltQueryMethods

# Type Alias: BuiltQueryMethods\<Arguments>

```ts
type BuiltQueryMethods<Arguments>: [QueryBy<Arguments>, GetAllBy<Arguments>, GetBy<Arguments>, FindAllBy<Arguments>, FindBy<Arguments>];
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:199



---
url: /api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ByRoleMatcher

# Type Alias: ByRoleMatcher

```ts
type ByRoleMatcher: prettyFormat | string & object;
```

## Defined in

index.d.ts:207



---
url: /api/reactlynx-testing-library/TypeAlias.CreateFunction.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / CreateFunction

# Type Alias: CreateFunction()

```ts
type CreateFunction: (eventName: string, node: Document | Element | Window | Node, init?: object, options?: object) => Event;
```

## Parameters

| Parameter              | Type                                          |
| ---------------------- | --------------------------------------------- |
| `eventName`            | `string`                                      |
| `node`                 | `Document` \| `Element` \| `Window` \| `Node` |
| `init`?                | `object`                                      |
| `options`?             | `object`                                      |
| `options.defaultInit`? | `object`                                      |
| `options.EventType`?   | `string`                                      |

## Returns

`Event`

## Defined in

index.d.ts:318



---
url: /api/reactlynx-testing-library/TypeAlias.CreateObject.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / CreateObject

# Type Alias: CreateObject

```ts
type CreateObject: { [K in EventType]: Function };
```

## Defined in

index.d.ts:325



---
url: /api/reactlynx-testing-library/TypeAlias.ElementTree.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ElementTree

# Type Alias: ElementTree

```ts
type ElementTree: ReturnType<typeof initElementTree>;
```

The lynx element tree

## Defined in

index.d.ts:341



---
url: /api/reactlynx-testing-library/TypeAlias.EventType.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / EventType

# Type Alias: EventType

```ts
type EventType: 
  | "copy"
  | "cut"
  | "paste"
  | "compositionEnd"
  | "compositionStart"
  | "compositionUpdate"
  | "keyDown"
  | "keyPress"
  | "keyUp"
  | "focus"
  | "blur"
  | "focusIn"
  | "focusOut"
  | "change"
  | "input"
  | "invalid"
  | "submit"
  | "reset"
  | "click"
  | "contextMenu"
  | "dblClick"
  | "drag"
  | "dragEnd"
  | "dragEnter"
  | "dragExit"
  | "dragLeave"
  | "dragOver"
  | "dragStart"
  | "drop"
  | "mouseDown"
  | "mouseEnter"
  | "mouseLeave"
  | "mouseMove"
  | "mouseOut"
  | "mouseOver"
  | "mouseUp"
  | "popState"
  | "select"
  | "touchCancel"
  | "touchEnd"
  | "touchMove"
  | "touchStart"
  | "resize"
  | "scroll"
  | "wheel"
  | "abort"
  | "canPlay"
  | "canPlayThrough"
  | "durationChange"
  | "emptied"
  | "encrypted"
  | "ended"
  | "loadedData"
  | "loadedMetadata"
  | "loadStart"
  | "pause"
  | "play"
  | "playing"
  | "progress"
  | "rateChange"
  | "seeked"
  | "seeking"
  | "stalled"
  | "suspend"
  | "timeUpdate"
  | "volumeChange"
  | "waiting"
  | "load"
  | "error"
  | "animationStart"
  | "animationEnd"
  | "animationIteration"
  | "transitionCancel"
  | "transitionEnd"
  | "transitionRun"
  | "transitionStart"
  | "doubleClick"
  | "pointerOver"
  | "pointerEnter"
  | "pointerDown"
  | "pointerMove"
  | "pointerUp"
  | "pointerCancel"
  | "pointerOut"
  | "pointerLeave"
  | "gotPointerCapture"
  | "lostPointerCapture"
  | "offline"
  | "online"
  | "pageHide"
  | "pageShow";
```

## Defined in

index.d.ts:349



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllBy.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllBy

# Type Alias: FindAllBy\<Arguments>

```ts
type FindAllBy<Arguments>: QueryMethod<[Arguments[0], Arguments[1]?, waitForOptions?], Promise<HTMLElement[]>>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:449



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllByBoundAttribute

# Type Alias: FindAllByBoundAttribute()\<T>

```ts
type FindAllByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T[]>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?               | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`\[]>

## Defined in

index.d.ts:458



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllByRole

# Type Alias: FindAllByRole()\<T>

```ts
type FindAllByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions, waitForElementOptions?: waitForOptions) => Promise<T[]>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `role`                   | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md)   |
| `options`?               | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)   |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`\[]>

## Defined in

index.d.ts:477



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllByText

# Type Alias: FindAllByText()\<T>

```ts
type FindAllByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T[]>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `container`              | `HTMLElement`                                                                                               |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?               | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)                              |

## Returns

`Promise`\<`T`\[]>

## Defined in

index.d.ts:492



---
url: /api/reactlynx-testing-library/TypeAlias.FindBy.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindBy

# Type Alias: FindBy\<Arguments>

```ts
type FindBy<Arguments>: QueryMethod<[Arguments[0], Arguments[1]?, waitForOptions?], Promise<HTMLElement>>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:507



---
url: /api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindByBoundAttribute

# Type Alias: FindByBoundAttribute()\<T>

```ts
type FindByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?               | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:516



---
url: /api/reactlynx-testing-library/TypeAlias.FindByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindByRole

# Type Alias: FindByRole()\<T>

```ts
type FindByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions, waitForElementOptions?: waitForOptions) => Promise<T>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `role`                   | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md)   |
| `options`?               | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)   |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:535



---
url: /api/reactlynx-testing-library/TypeAlias.FindByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindByText

# Type Alias: FindByText()\<T>

```ts
type FindByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `container`              | `HTMLElement`                                                                                               |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?               | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)                              |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:550



---
url: /api/reactlynx-testing-library/TypeAlias.FireFunction.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FireFunction

# Type Alias: FireFunction()

```ts
type FireFunction: (element: Document | Element | Window | Node, event: Event) => boolean;
```

## Parameters

| Parameter | Type                                          |
| --------- | --------------------------------------------- |
| `element` | `Document` \| `Element` \| `Window` \| `Node` |
| `event`   | `Event`                                       |

## Returns

`boolean`

## Defined in

index.d.ts:567



---
url: /api/reactlynx-testing-library/TypeAlias.FireObject.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FireObject

# Type Alias: FireObject

```ts
type FireObject: { [K in EventType]: Function };
```

## Defined in

index.d.ts:572



---
url: /api/reactlynx-testing-library/TypeAlias.GetAllBy.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetAllBy

# Type Alias: GetAllBy\<Arguments>

```ts
type GetAllBy<Arguments>: QueryMethod<Arguments, HTMLElement[]>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:579



---
url: /api/reactlynx-testing-library/TypeAlias.GetBy.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetBy

# Type Alias: GetBy\<Arguments>

```ts
type GetBy<Arguments>: QueryMethod<Arguments, HTMLElement>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:616



---
url: /api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetByBoundAttribute

# Type Alias: GetByBoundAttribute()\<T>

```ts
type GetByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions) => T;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`T`

## Defined in

index.d.ts:622



---
url: /api/reactlynx-testing-library/TypeAlias.GetByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetByRole

# Type Alias: GetByRole()\<T>

```ts
type GetByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions) => T;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                         |
| ----------- | ---------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                |
| `role`      | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md) |
| `options`?  | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md) |

## Returns

`T`

## Defined in

index.d.ts:640



---
url: /api/reactlynx-testing-library/TypeAlias.GetByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetByText

# Type Alias: GetByText()\<T>

```ts
type GetByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => T;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                                                        |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                                               |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?  | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |

## Returns

`T`

## Defined in

index.d.ts:654



---
url: /api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetErrorFunction

# Type Alias: GetErrorFunction()\<Arguments>

```ts
type GetErrorFunction<Arguments>: (c: Element | null, ...args: Arguments) => string;
```

## Type Parameters

| Type Parameter                 | Default type |
| ------------------------------ | ------------ |
| `Arguments` _extends_ `any`\[] | \[`string`]  |

## Parameters

| Parameter | Type                |
| --------- | ------------------- |
| `c`       | `Element` \| `null` |
| ...`args` | `Arguments`         |

## Returns

`string`

## Defined in

index.d.ts:679



---
url: /api/reactlynx-testing-library/TypeAlias.Match.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Match

# Type Alias: Match()

```ts
type Match: (textToMatch: string, node: HTMLElement | null, matcher: Matcher, options?: MatcherOptions) => boolean;
```

## Parameters

| Parameter     | Type                                                                           |
| ------------- | ------------------------------------------------------------------------------ |
| `textToMatch` | `string`                                                                       |
| `node`        | `HTMLElement` \| `null`                                                        |
| `matcher`     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?    | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`boolean`

## Defined in

index.d.ts:913



---
url: /api/reactlynx-testing-library/TypeAlias.Matcher.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Matcher

# Type Alias: Matcher

```ts
type Matcher: MatcherFunction | RegExp | number | string;
```

## Defined in

index.d.ts:920



---
url: /api/reactlynx-testing-library/TypeAlias.MatcherFunction.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / MatcherFunction

# Type Alias: MatcherFunction()

```ts
type MatcherFunction: (content: string, element: Element | null) => boolean;
```

## Parameters

| Parameter | Type                |
| --------- | ------------------- |
| `content` | `string`            |
| `element` | `Element` \| `null` |

## Returns

`boolean`

## Defined in

index.d.ts:922



---
url: /api/reactlynx-testing-library/TypeAlias.Method.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Method

# Type Alias: Method

```ts
type Method: 
  | "AltText"
  | "alttext"
  | "DisplayValue"
  | "displayvalue"
  | "LabelText"
  | "labeltext"
  | "PlaceholderText"
  | "placeholdertext"
  | "Role"
  | "role"
  | "TestId"
  | "testid"
  | "Text"
  | "text"
  | "Title"
  | "title";
```

## Defined in

index.d.ts:938



---
url: /api/reactlynx-testing-library/TypeAlias.NormalizerFn.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / NormalizerFn

# Type Alias: NormalizerFn()

```ts
type NormalizerFn: (text: string) => string;
```

## Parameters

| Parameter | Type     |
| --------- | -------- |
| `text`    | `string` |

## Returns

`string`

## Defined in

index.d.ts:956



---
url: /api/reactlynx-testing-library/TypeAlias.Query.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Query

# Type Alias: Query()

```ts
type Query: (container: HTMLElement, ...args: any[]) => 
  | Error
  | HTMLElement
  | HTMLElement[]
  | Promise<HTMLElement[]>
  | Promise<HTMLElement>
  | null;
```

## Parameters

| Parameter   | Type          |
| ----------- | ------------- |
| `container` | `HTMLElement` |
| ...`args`   | `any`\[]      |

## Returns

\| `Error`
\| `HTMLElement`
\| `HTMLElement`\[]
\| `Promise`\<`HTMLElement`\[]>
\| `Promise`\<`HTMLElement`>
\| `null`

## Defined in

index.d.ts:1057



---
url: /api/reactlynx-testing-library/TypeAlias.QueryArgs.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryArgs

# Type Alias: QueryArgs

```ts
type QueryArgs: [string, QueryOptions?];
```

## Defined in

index.d.ts:1102



---
url: /api/reactlynx-testing-library/TypeAlias.QueryBy.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryBy

# Type Alias: QueryBy\<Arguments>

```ts
type QueryBy<Arguments>: QueryMethod<Arguments, HTMLElement | null>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:1104



---
url: /api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryByAttribute

# Type Alias: QueryByAttribute()

```ts
type QueryByAttribute: (attribute: string, container: HTMLElement, id: Matcher, options?: MatcherOptions) => HTMLElement | null;
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`HTMLElement` | `null`

## Defined in

index.d.ts:1113



---
url: /api/reactlynx-testing-library/TypeAlias.RenderResult.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderResult

# Type Alias: RenderResult\<Q>

```ts
type RenderResult<Q>: object & { [P in keyof Q]: BoundFunction<Q[P]> };
```

The result of [render](/api/reactlynx-testing-library/Function.render.md)

## Type declaration

### container

```ts
container: LynxElement;
```

### rerender()

```ts
rerender: (ui: prettyFormat) => void;
```

#### Parameters

| Parameter | Type                                                                      |
| --------- | ------------------------------------------------------------------------- |
| `ui`      | [`prettyFormat`](/api/reactlynx-testing-library/Variable.prettyFormat.md) |

#### Returns

`void`

### unmount()

```ts
unmount: () => boolean;
```

#### Returns

`boolean`

## Type Parameters

| Type Parameter                                                                 | Default type                                                              |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |

## Defined in

index.d.ts:1424



---
url: /api/reactlynx-testing-library/TypeAlias.Screen.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Screen

# Type Alias: Screen\<Q>

```ts
type Screen<Q>: BoundFunctions<Q> & object;
```

## Type declaration

### debug()

```ts
debug: (element?: (Element | HTMLDocument)[] | Element | HTMLDocument, maxLength?: number, options?: prettyFormat) => void;
```

Convenience function for `pretty-dom` which also allows an array
of elements

#### Parameters

| Parameter    | Type                                                                      |
| ------------ | ------------------------------------------------------------------------- |
| `element`?   | (`Element` \| `HTMLDocument`)\[] \| `Element` \| `HTMLDocument`           |
| `maxLength`? | `number`                                                                  |
| `options`?   | [`prettyFormat`](/api/reactlynx-testing-library/Variable.prettyFormat.md) |

#### Returns

`void`

### logTestingPlaygroundURL()

```ts
logTestingPlaygroundURL: (element?: Element | HTMLDocument) => string;
```

Convenience function for `Testing Playground` which logs and returns the URL that
can be opened in a browser

#### Parameters

| Parameter  | Type                        |
| ---------- | --------------------------- |
| `element`? | `Element` \| `HTMLDocument` |

#### Returns

`string`

## Type Parameters

| Type Parameter                                                                 | Default type                                                              |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |

## Defined in

index.d.ts:1430



---
url: /api/reactlynx-testing-library/TypeAlias.Variant.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Variant

# Type Alias: Variant

```ts
type Variant: 
  | "find"
  | "findAll"
  | "get"
  | "getAll"
  | "query"
  | "queryAll";
```

## Defined in

index.d.ts:1465



---
url: /api/reactlynx-testing-library/Variable.prettyFormat.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / prettyFormat

# Variable: prettyFormat

```ts
prettyFormat: any;
```



---
url: /api/reactlynx-testing-library/Variable.screen.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / screen

# Variable: screen

```ts
const screen: Screen;
```

## Defined in

index.d.ts:1448



---
url: /api/reactlynx-testing-library/index.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


# @lynx-js/react/testing-library

ReactLynx Testing Library is a simple and complete ReactLynx unit testing library that encourages good testing practices.

> Inspired completely by [react-testing-library](https://github.com/testing-library/react-testing-library)

Similar to [react-testing-library](https://github.com/testing-library/react-testing-library), this library is designed to test your ReactLynx components in the same way you would test React components using react-testing-library.

## Setup

Setup vitest:

```js
// vitest.config.js
import { defineConfig, mergeConfig } from 'vitest/config';
import { createVitestConfig } from '@lynx-js/react/testing-library/vitest-config';

const defaultConfig = createVitestConfig();
const config = defineConfig({
  test: {
    // ...
  },
});

export default mergeConfig(defaultConfig, config);
```

Then you can start writing tests and run them with vitest!

## Usage

```js
import '@testing-library/jest-dom';
import { test, expect } from 'vitest';
import { render } from '@lynx-js/react/testing-library';

test('renders options.wrapper around node', async () => {
  const WrapperComponent = ({ children }) => (
    <view data-testid='wrapper'>{children}</view>
  );
  const Comp = () => {
    return <view data-testid='inner' style='background-color: yellow;' />;
  };
  const { container, getByTestId } = render(<Comp />, {
    wrapper: WrapperComponent,
  });
  expect(getByTestId('wrapper')).toBeInTheDocument();
  expect(container.firstChild).toMatchInlineSnapshot(`
    <view
      data-testid="wrapper"
    >
      <view
        data-testid="inner"
        style="background-color: yellow;"
      />
    </view>
  `);
});
```

💡 Since our testing environment (`@lynx-js/testing-environment`) is based on jsdom, You may also be interested in installing `@testing-library/jest-dom` so you can use
[the custom jest matchers](https://github.com/testing-library/jest-dom).

## Examples

See our [examples](https://github.com/lynx-family/lynx-stack/tree/main/packages/react/testing-library/src/__tests__) for more usage.

## Credits

- [Testing Library](https://testing-library.com/) for the testing utilities and good practices for React testing.

## References

### QueryByBoundAttribute

Re-exports [QueryByBoundAttribute](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)

***

### QueryByRole

Re-exports [QueryByRole](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md)

***

### QueryByText

Re-exports [QueryByText](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)

***

### QueryMethod

Re-exports [QueryMethod](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md)

***

### SelectorMatcherOptions

Re-exports [SelectorMatcherOptions](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)

***

### WithSuggest

Re-exports [WithSuggest](/api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md)

## Namespaces

| Namespace                                                                | Description |
| ------------------------------------------------------------------------ | ----------- |
| [queries](/api/reactlynx-testing-library/Namespace.queries.md)           | -           |
| [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) | -           |

## Classes

| Class                                                                    | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [LynxTestingEnv](/api/reactlynx-testing-library/Class.LynxTestingEnv.md) | A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md), notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js. |

## Interfaces

| Interface                                                                                        | Description                                                                         |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [ByRoleOptions](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)                       | -                                                                                   |
| [Config](/api/reactlynx-testing-library/Interface.Config.md)                                     | -                                                                                   |
| [ConfigFn](/api/reactlynx-testing-library/Interface.ConfigFn.md)                                 | -                                                                                   |
| [DefaultNormalizerOptions](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md) | -                                                                                   |
| [LogRolesOptions](/api/reactlynx-testing-library/Interface.LogRolesOptions.md)                   | -                                                                                   |
| [MatcherOptions](/api/reactlynx-testing-library/Interface.MatcherOptions.md)                     | -                                                                                   |
| [NormalizerOptions](/api/reactlynx-testing-library/Interface.NormalizerOptions.md)               | -                                                                                   |
| [PrettyDOMOptions](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md)                 | -                                                                                   |
| [Queries](/api/reactlynx-testing-library/Interface.Queries.md)                                   | -                                                                                   |
| [QueryOptions](/api/reactlynx-testing-library/Interface.QueryOptions.md)                         | -                                                                                   |
| [RenderHookOptions](/api/reactlynx-testing-library/Interface.RenderHookOptions.md)               | The options for [renderHook](/api/reactlynx-testing-library/Function.renderHook.md) |
| [RenderHookResult](/api/reactlynx-testing-library/Interface.RenderHookResult.md)                 | The result of [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)   |
| [RenderOptions](/api/reactlynx-testing-library/Interface.RenderOptions.md)                       | The options for [render](/api/reactlynx-testing-library/Function.render.md).        |
| [Suggestion](/api/reactlynx-testing-library/Interface.Suggestion.md)                             | -                                                                                   |
| [waitForOptions](/api/reactlynx-testing-library/Interface.waitForOptions.md)                     | -                                                                                   |

## Type Aliases

| Type alias                                                                                     | Description                                                               |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [AllByAttribute](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md)                   | -                                                                         |
| [AllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)         | -                                                                         |
| [AllByRole](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)                             | -                                                                         |
| [AllByText](/api/reactlynx-testing-library/TypeAlias.AllByText.md)                             | -                                                                         |
| [BoundFunction](/api/reactlynx-testing-library/TypeAlias.BoundFunction.md)                     | -                                                                         |
| [BoundFunctions](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md)                   | -                                                                         |
| [BuiltQueryMethods](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md)             | -                                                                         |
| [ByRoleMatcher](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md)                     | -                                                                         |
| [CreateFunction](/api/reactlynx-testing-library/TypeAlias.CreateFunction.md)                   | -                                                                         |
| [CreateObject](/api/reactlynx-testing-library/TypeAlias.CreateObject.md)                       | -                                                                         |
| [ElementTree](/api/reactlynx-testing-library/TypeAlias.ElementTree.md)                         | The lynx element tree                                                     |
| [EventType](/api/reactlynx-testing-library/TypeAlias.EventType.md)                             | -                                                                         |
| [FindAllBy](/api/reactlynx-testing-library/TypeAlias.FindAllBy.md)                             | -                                                                         |
| [FindAllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md) | -                                                                         |
| [FindAllByRole](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md)                     | -                                                                         |
| [FindAllByText](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)                     | -                                                                         |
| [FindBy](/api/reactlynx-testing-library/TypeAlias.FindBy.md)                                   | -                                                                         |
| [FindByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)       | -                                                                         |
| [FindByRole](/api/reactlynx-testing-library/TypeAlias.FindByRole.md)                           | -                                                                         |
| [FindByText](/api/reactlynx-testing-library/TypeAlias.FindByText.md)                           | -                                                                         |
| [FireFunction](/api/reactlynx-testing-library/TypeAlias.FireFunction.md)                       | -                                                                         |
| [FireObject](/api/reactlynx-testing-library/TypeAlias.FireObject.md)                           | -                                                                         |
| [GetAllBy](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md)                               | -                                                                         |
| [GetBy](/api/reactlynx-testing-library/TypeAlias.GetBy.md)                                     | -                                                                         |
| [GetByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)         | -                                                                         |
| [GetByRole](/api/reactlynx-testing-library/TypeAlias.GetByRole.md)                             | -                                                                         |
| [GetByText](/api/reactlynx-testing-library/TypeAlias.GetByText.md)                             | -                                                                         |
| [GetErrorFunction](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)               | -                                                                         |
| [Match](/api/reactlynx-testing-library/TypeAlias.Match.md)                                     | -                                                                         |
| [Matcher](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                 | -                                                                         |
| [MatcherFunction](/api/reactlynx-testing-library/TypeAlias.MatcherFunction.md)                 | -                                                                         |
| [Method](/api/reactlynx-testing-library/TypeAlias.Method.md)                                   | -                                                                         |
| [NormalizerFn](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md)                       | -                                                                         |
| [Query](/api/reactlynx-testing-library/TypeAlias.Query.md)                                     | -                                                                         |
| [QueryArgs](/api/reactlynx-testing-library/TypeAlias.QueryArgs.md)                             | -                                                                         |
| [QueryBy](/api/reactlynx-testing-library/TypeAlias.QueryBy.md)                                 | -                                                                         |
| [QueryByAttribute](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md)               | -                                                                         |
| [RenderResult](/api/reactlynx-testing-library/TypeAlias.RenderResult.md)                       | The result of [render](/api/reactlynx-testing-library/Function.render.md) |
| [Screen](/api/reactlynx-testing-library/TypeAlias.Screen.md)                                   | -                                                                         |
| [Variant](/api/reactlynx-testing-library/TypeAlias.Variant.md)                                 | -                                                                         |

## Variables

| Variable                                                                | Description |
| ----------------------------------------------------------------------- | ----------- |
| [prettyFormat](/api/reactlynx-testing-library/Variable.prettyFormat.md) | -           |
| [screen](/api/reactlynx-testing-library/Variable.screen.md)             | -           |

## Functions

| Function                                                                                          | Description                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [buildQueries](/api/reactlynx-testing-library/Function.buildQueries.md)                           | -                                                                                                                                                                  |
| [cleanup](/api/reactlynx-testing-library/Function.cleanup.md)                                     | Cleanup elements rendered to the page and Preact trees that were mounted with render.                                                                              |
| [computeHeadingLevel](/api/reactlynx-testing-library/Function.computeHeadingLevel.md)             | -                                                                                                                                                                  |
| [configure](/api/reactlynx-testing-library/Function.configure.md)                                 | -                                                                                                                                                                  |
| [createEvent](/api/reactlynx-testing-library/Function.createEvent.md)                             | -                                                                                                                                                                  |
| [findAllByAltText](/api/reactlynx-testing-library/Function.findAllByAltText.md)                   | -                                                                                                                                                                  |
| [findAllByDisplayValue](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md)         | -                                                                                                                                                                  |
| [findAllByLabelText](/api/reactlynx-testing-library/Function.findAllByLabelText.md)               | -                                                                                                                                                                  |
| [findAllByPlaceholderText](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md)   | -                                                                                                                                                                  |
| [findAllByRole](/api/reactlynx-testing-library/Function.findAllByRole.md)                         | -                                                                                                                                                                  |
| [findAllByTestId](/api/reactlynx-testing-library/Function.findAllByTestId.md)                     | -                                                                                                                                                                  |
| [findAllByText](/api/reactlynx-testing-library/Function.findAllByText.md)                         | -                                                                                                                                                                  |
| [findAllByTitle](/api/reactlynx-testing-library/Function.findAllByTitle.md)                       | -                                                                                                                                                                  |
| [findByAltText](/api/reactlynx-testing-library/Function.findByAltText.md)                         | -                                                                                                                                                                  |
| [findByDisplayValue](/api/reactlynx-testing-library/Function.findByDisplayValue.md)               | -                                                                                                                                                                  |
| [findByLabelText](/api/reactlynx-testing-library/Function.findByLabelText.md)                     | -                                                                                                                                                                  |
| [findByPlaceholderText](/api/reactlynx-testing-library/Function.findByPlaceholderText.md)         | -                                                                                                                                                                  |
| [findByRole](/api/reactlynx-testing-library/Function.findByRole.md)                               | -                                                                                                                                                                  |
| [findByTestId](/api/reactlynx-testing-library/Function.findByTestId.md)                           | -                                                                                                                                                                  |
| [findByText](/api/reactlynx-testing-library/Function.findByText.md)                               | -                                                                                                                                                                  |
| [findByTitle](/api/reactlynx-testing-library/Function.findByTitle.md)                             | -                                                                                                                                                                  |
| [fireEvent](/api/reactlynx-testing-library/Function.fireEvent.md)                                 | -                                                                                                                                                                  |
| [getAllByAltText](/api/reactlynx-testing-library/Function.getAllByAltText.md)                     | -                                                                                                                                                                  |
| [getAllByDisplayValue](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md)           | -                                                                                                                                                                  |
| [getAllByLabelText](/api/reactlynx-testing-library/Function.getAllByLabelText.md)                 | -                                                                                                                                                                  |
| [getAllByPlaceholderText](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md)     | -                                                                                                                                                                  |
| [getAllByRole](/api/reactlynx-testing-library/Function.getAllByRole.md)                           | -                                                                                                                                                                  |
| [getAllByTestId](/api/reactlynx-testing-library/Function.getAllByTestId.md)                       | -                                                                                                                                                                  |
| [getAllByText](/api/reactlynx-testing-library/Function.getAllByText.md)                           | -                                                                                                                                                                  |
| [getAllByTitle](/api/reactlynx-testing-library/Function.getAllByTitle.md)                         | -                                                                                                                                                                  |
| [getByAltText](/api/reactlynx-testing-library/Function.getByAltText.md)                           | -                                                                                                                                                                  |
| [getByDisplayValue](/api/reactlynx-testing-library/Function.getByDisplayValue.md)                 | -                                                                                                                                                                  |
| [getByLabelText](/api/reactlynx-testing-library/Function.getByLabelText.md)                       | -                                                                                                                                                                  |
| [getByPlaceholderText](/api/reactlynx-testing-library/Function.getByPlaceholderText.md)           | -                                                                                                                                                                  |
| [getByRole](/api/reactlynx-testing-library/Function.getByRole.md)                                 | -                                                                                                                                                                  |
| [getByTestId](/api/reactlynx-testing-library/Function.getByTestId.md)                             | -                                                                                                                                                                  |
| [getByText](/api/reactlynx-testing-library/Function.getByText.md)                                 | -                                                                                                                                                                  |
| [getByTitle](/api/reactlynx-testing-library/Function.getByTitle.md)                               | -                                                                                                                                                                  |
| [getConfig](/api/reactlynx-testing-library/Function.getConfig.md)                                 | -                                                                                                                                                                  |
| [getDefaultNormalizer](/api/reactlynx-testing-library/Function.getDefaultNormalizer.md)           | -                                                                                                                                                                  |
| [getElementError](/api/reactlynx-testing-library/Function.getElementError.md)                     | -                                                                                                                                                                  |
| [getNodeText](/api/reactlynx-testing-library/Function.getNodeText.md)                             | -                                                                                                                                                                  |
| [getQueriesForElement](/api/reactlynx-testing-library/Function.getQueriesForElement.md)           | -                                                                                                                                                                  |
| [getRoles](/api/reactlynx-testing-library/Function.getRoles.md)                                   | -                                                                                                                                                                  |
| [getSuggestedQuery](/api/reactlynx-testing-library/Function.getSuggestedQuery.md)                 | -                                                                                                                                                                  |
| [isInaccessible](/api/reactlynx-testing-library/Function.isInaccessible.md)                       | [https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible](https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible) |
| [logDOM](/api/reactlynx-testing-library/Function.logDOM.md)                                       | -                                                                                                                                                                  |
| [logRoles](/api/reactlynx-testing-library/Function.logRoles.md)                                   | -                                                                                                                                                                  |
| [prettyDOM](/api/reactlynx-testing-library/Function.prettyDOM.md)                                 | -                                                                                                                                                                  |
| [queryAllByAltText](/api/reactlynx-testing-library/Function.queryAllByAltText.md)                 | -                                                                                                                                                                  |
| [queryAllByAttribute](/api/reactlynx-testing-library/Function.queryAllByAttribute.md)             | -                                                                                                                                                                  |
| [queryAllByDisplayValue](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md)       | -                                                                                                                                                                  |
| [queryAllByLabelText](/api/reactlynx-testing-library/Function.queryAllByLabelText.md)             | -                                                                                                                                                                  |
| [queryAllByPlaceholderText](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md) | -                                                                                                                                                                  |
| [queryAllByRole](/api/reactlynx-testing-library/Function.queryAllByRole.md)                       | -                                                                                                                                                                  |
| [queryAllByTestId](/api/reactlynx-testing-library/Function.queryAllByTestId.md)                   | -                                                                                                                                                                  |
| [queryAllByText](/api/reactlynx-testing-library/Function.queryAllByText.md)                       | -                                                                                                                                                                  |
| [queryAllByTitle](/api/reactlynx-testing-library/Function.queryAllByTitle.md)                     | -                                                                                                                                                                  |
| [queryByAltText](/api/reactlynx-testing-library/Function.queryByAltText.md)                       | -                                                                                                                                                                  |
| [queryByAttribute](/api/reactlynx-testing-library/Function.queryByAttribute.md)                   | -                                                                                                                                                                  |
| [queryByDisplayValue](/api/reactlynx-testing-library/Function.queryByDisplayValue.md)             | -                                                                                                                                                                  |
| [queryByLabelText](/api/reactlynx-testing-library/Function.queryByLabelText.md)                   | -                                                                                                                                                                  |
| [queryByPlaceholderText](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md)       | -                                                                                                                                                                  |
| [queryByRole](/api/reactlynx-testing-library/Function.queryByRole.md)                             | -                                                                                                                                                                  |
| [queryByTestId](/api/reactlynx-testing-library/Function.queryByTestId.md)                         | -                                                                                                                                                                  |
| [queryByText](/api/reactlynx-testing-library/Function.queryByText.md)                             | -                                                                                                                                                                  |
| [queryByTitle](/api/reactlynx-testing-library/Function.queryByTitle.md)                           | -                                                                                                                                                                  |
| [render](/api/reactlynx-testing-library/Function.render.md)                                       | Render into the page. It should be used with cleanup.                                                                                                              |
| [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)                               | Allows you to render a hook within a test React component without having to create that component yourself.                                                        |
| [waitFor](/api/reactlynx-testing-library/Function.waitFor.md)                                     | -                                                                                                                                                                  |
| [waitForElementToBeRemoved](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md) | -                                                                                                                                                                  |
| [waitSchedule](/api/reactlynx-testing-library/Function.waitSchedule.md)                           | Wait for the next event loop.                                                                                                                                      |
| [within](/api/reactlynx-testing-library/Function.within.md)                                       | -                                                                                                                                                                  |



---
url: /api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queries](/api/reactlynx-testing-library/Namespace.queries.md) / QueryByBoundAttribute

# Type Alias: QueryByBoundAttribute()\<T>

```ts
type QueryByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions) => T | null;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`T` | `null`

## Defined in

index.d.ts:1122



---
url: /api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queries](/api/reactlynx-testing-library/Namespace.queries.md) / QueryByRole

# Type Alias: QueryByRole()\<T>

```ts
type QueryByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions) => T | null;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                         |
| ----------- | ---------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                |
| `role`      | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md) |
| `options`?  | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md) |

## Returns

`T` | `null`

## Defined in

index.d.ts:1140



---
url: /api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queries](/api/reactlynx-testing-library/Namespace.queries.md) / QueryByText

# Type Alias: QueryByText()\<T>

```ts
type QueryByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => T | null;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                                                        |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                                               |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?  | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |

## Returns

`T` | `null`

## Defined in

index.d.ts:1154



---
url: /api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) / SelectorMatcherOptions

# Interface: SelectorMatcherOptions

## Extends

- [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`collapseWhitespace`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#collapsewhitespace)

#### Defined in

index.d.ts:932

***

### exact?

```ts
optional exact: boolean;
```

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`exact`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#exact)

#### Defined in

index.d.ts:928

***

### ignore?

```ts
optional ignore: string | boolean;
```

#### Defined in

index.d.ts:1453

***

### normalizer?

```ts
optional normalizer: NormalizerFn;
```

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`normalizer`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#normalizer)

#### Defined in

index.d.ts:933

***

### selector?

```ts
optional selector: string;
```

#### Defined in

index.d.ts:1452

***

### suggest?

```ts
optional suggest: boolean;
```

suppress suggestions for a specific query

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`suggest`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#suggest)

#### Defined in

index.d.ts:935

***

### trim?

```ts
optional trim: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`trim`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#trim)

#### Defined in

index.d.ts:930



---
url: /api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) / QueryMethod

# Type Alias: QueryMethod()\<Arguments, Return>

```ts
type QueryMethod<Arguments, Return>: (container: HTMLElement, ...args: Arguments) => Return;
```

query methods have a common call signature. Only the return type differs.

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |
| `Return`                       |

## Parameters

| Parameter   | Type          |
| ----------- | ------------- |
| `container` | `HTMLElement` |
| ...`args`   | `Arguments`   |

## Returns

`Return`

## Defined in

index.d.ts:1193



---
url: /api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md
---

{/*
  * This file is generated by @lynx-js/tool-typedoc.
  * Do not edit this file directly.
  * @generated
  */}

{/* Import all components as Lynx to allow dynamic lookup in TSDoc writings. */}


[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) / WithSuggest

# Type Alias: WithSuggest

```ts
type WithSuggest: object;
```

## Type declaration

### suggest?

```ts
optional suggest: boolean;
```

## Defined in

index.d.ts:1502



---
url: /api/rspeedy/index.md
---




---
url: /api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [CustomizedSchemaFn](/api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md)

## CustomizedSchemaFn type

Customize the generated schema.

**Signature:**

```typescript
export type CustomizedSchemaFn = (url: string) => string | Record<string, string>;
```



---
url: /api/rspeedy/qrcode-rsbuild-plugin.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md)

## qrcode-rsbuild-plugin package

A rsbuild plugin that print the template.js url using QRCode.

## Functions

| Function                                                                    | Description                                  |
| --------------------------------------------------------------------------- | -------------------------------------------- |
| [pluginQRCode(options)](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md) | Create a rsbuild plugin for printing QRCode. |

## Interfaces

| Interface                                                                        | Description                                                                                   |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md) | The options for [pluginQRCode()](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md)<!-- -->. |

## Type Aliases

| Type Alias                                                                     | Description                     |
| ------------------------------------------------------------------------------ | ------------------------------- |
| [CustomizedSchemaFn](/api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md) | Customize the generated schema. |



---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [pluginQRCode](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md)

## pluginQRCode() function

Create a rsbuild plugin for printing QRCode.

**Signature:**

```typescript
export declare function pluginQRCode(options?: PluginQRCodeOptions): RsbuildPlugin;
```

## Parameters

| Parameter | Type                                                                             | Description  |
| --------- | -------------------------------------------------------------------------------- | ------------ |
| options   | [PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md) | _(Optional)_ |

**Returns:**

RsbuildPlugin

## Example

```ts
// rsbuild.config.ts
import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'
export default {
  plugins: [pluginQRCode()],
}
```



---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md)

## PluginQRCodeOptions interface

The options for [pluginQRCode()](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md)<!-- -->.

**Signature:**

```typescript
export interface PluginQRCodeOptions 
```

## Properties

| Property                                                                    | Modifiers | Type                                                                                        | Description                                  |
| --------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [schema?](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.schema.md) |           | [CustomizedSchemaFn](/api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md) \| undefined | _(Optional)_ Customize the generated schema. |



---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.schema.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md) > [schema](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.schema.md)

## PluginQRCodeOptions.schema property

Customize the generated schema.

**Signature:**

```typescript
schema?: CustomizedSchemaFn | undefined;
```

## Example 1

```js
import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  plugins: [
    pluginQRCode({
      schema(url) {
        return `lynx://${url}?dev=1`
      },
    }),
  ],
})
```

## Example 2

- Use multiple schemas:

You may press `a` in the terminal to switch between schemas.

```js
import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  plugins: [
    pluginQRCode({
      schema(url) {
        return {
          http: url,
          foo: `foo://lynx?url=${encodeURIComponent(url)}&dev=1`,
          bar: `bar://lynx?url=${encodeURIComponent(url)}`,
        }
      },
    }),
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.compileronly.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md) > [compilerOnly](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.compileronly.md)

## AddComponentElementConfig.compilerOnly property

Whether to only add component element during compilation

**Signature:**

```typescript
compilerOnly: boolean
```

## Example

Note that this only take effects on `Component` imported from [CompatVisitorConfig.oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        addComponentElement: { compilerOnly: true }
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md)

## AddComponentElementConfig interface

Controls whether to add wrapper elements for components

**Signature:**

```typescript
export interface AddComponentElementConfig 
```

## Remarks

Default value: `false`

## Properties

| Property                                                                                    | Modifiers | Type    | Description                                              |
| ------------------------------------------------------------------------------------------- | --------- | ------- | -------------------------------------------------------- |
| [compilerOnly](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.compileronly.md) |           | boolean | Whether to only add component element during compilation |



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [addComponentElement](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md)

## CompatVisitorConfig.addComponentElement property

Controls whether to add wrapper elements for components

**Signature:**

```typescript
addComponentElement: boolean | AddComponentElementConfig
```

## Remarks

Default value: `false`

## Example 1

Add a `<view>` wrapper element for all components during runtime.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        addComponentElement: true
      },
    })
  ],
})
```

## Example 2

Only add component element during compilation. Note that this only take effects on `Component` imported from [CompatVisitorConfig.oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        addComponentElement: { compilerOnly: true }
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.additionalcomponentattributes.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [additionalComponentAttributes](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.additionalcomponentattributes.md)

## CompatVisitorConfig.additionalComponentAttributes property

Specifies additional component attributes list, these attributes will be passed to the wrapped `<view>` instead of the component.

**Signature:**

```typescript
additionalComponentAttributes: Array<string>
```

## Remarks

This only takes effect when [CompatVisitorConfig.addComponentElement](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md) is enabled.

Default value: `[]`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        additionalComponentAttributes: ['custom-attr', 'data-special']
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.componentspkg.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [componentsPkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.componentspkg.md)

## CompatVisitorConfig.componentsPkg property

Specifies the list of component package names that need compatibility processing

**Signature:**

```typescript
componentsPkg: Array<string>
```

## Remarks

Default value: `['@lynx-js/react-components']`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        componentsPkg: ['@my-org/components', '@legacy/ui-kit']
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.darkmode.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [darkMode](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.darkmode.md)

## CompatVisitorConfig.darkMode property

> Warning: This API is now obsolete.
>
> Dark mode configuration

**Signature:**

```typescript
darkMode?: boolean | DarkModeConfig
```

## Remarks

Default value: `None`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        darkMode: true
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [disableDeprecatedWarning](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md)

## CompatVisitorConfig.disableDeprecatedWarning property

Whether to disable deprecated warnings

**Signature:**

```typescript
disableDeprecatedWarning: boolean
```

## Remarks

Default value: `false`

## Example

Disable all the `DEPRECATED:` warnings.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        disableDeprecatedWarning: true
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md)

## CompatVisitorConfig interface

The `compat` option controls compatibilities with ReactLynx2.0.

**Signature:**

```typescript
export interface CompatVisitorConfig 
```

## Remarks

These options should only be used for migrating from ReactLynx2.0.

## Properties

| Property                                                                                                                | Modifiers | Type                                                                                                   | Description                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [addComponentElement](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md)                     |           | boolean \| [AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md) | Controls whether to add wrapper elements for components                                                                                       |
| [additionalComponentAttributes](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.additionalcomponentattributes.md) |           | Array\<string>                                                                                         | Specifies additional component attributes list, these attributes will be passed to the wrapped <code>\<view></code> instead of the component. |
| [componentsPkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.componentspkg.md)                                 |           | Array\<string>                                                                                         | Specifies the list of component package names that need compatibility processing                                                              |
| [darkMode?](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.darkmode.md)                                          |           | boolean \| DarkModeConfig                                                                              | _(Optional)_                                                                                                                                  |
| [disableDeprecatedWarning](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md)           |           | boolean                                                                                                | Whether to disable deprecated warnings                                                                                                        |
| [newRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md)                                 |           | string                                                                                                 | Specifies the new runtime package name                                                                                                        |
| [oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)                                 |           | Array\<string>                                                                                         | Specifies the list of old runtime package names that need compatibility processing                                                            |
| [removeComponentAttrRegex?](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.removecomponentattrregex.md)          |           | string                                                                                                 | _(Optional)_ Regular expression used to remove component attributes                                                                           |
| [simplifyCtorLikeReactLynx2](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md)       |           | boolean                                                                                                | Whether to simplify constructor calls like ReactLynx 2                                                                                        |



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [newRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md)

## CompatVisitorConfig.newRuntimePkg property

Specifies the new runtime package name

**Signature:**

```typescript
newRuntimePkg: string
```

## Remarks

Default value: `'@lynx-js/react'`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        newRuntimePkg: '@my-org/react'
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)

## CompatVisitorConfig.oldRuntimePkg property

Specifies the list of old runtime package names that need compatibility processing

**Signature:**

```typescript
oldRuntimePkg: Array<string>
```

## Remarks

Default value: `['@lynx-js/react-runtime']`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        oldRuntimePkg: ['@my-org/runtime', '@legacy/runtime']
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.removecomponentattrregex.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [removeComponentAttrRegex](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.removecomponentattrregex.md)

## CompatVisitorConfig.removeComponentAttrRegex property

> Warning: This API is now obsolete.
>
> It's recommended to use `background-only`<!-- -->.
>
> If your code depends on this switch, when distributing it to other projects through npm packages or other means, you'll also need to enable this switch. This will lead to the proliferation of switches, which is not conducive to code reuse between different projects.

Regular expression used to remove component attributes

**Signature:**

```typescript
removeComponentAttrRegex?: string
```

## Remarks

Default value: `None`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        removeComponentAttrRegex: '^data-test-'
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [simplifyCtorLikeReactLynx2](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md)

## CompatVisitorConfig.simplifyCtorLikeReactLynx2 property

> Warning: This API is now obsolete.
>
> Using `simplifyCtorLikeReactLynx2` is not recommended as it introduces implicit behaviors that can:
>
> - Make code harder to understand and maintain
>
> - Create hidden dependencies between components
>
> - Complicate debugging and testing processes
>
> Instead, use `background-only` on class methods for explicit and maintainable behavior

Whether to simplify constructor calls like ReactLynx 2

**Signature:**

```typescript
simplifyCtorLikeReactLynx2: boolean
```

## Remarks

Default value: `false`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        simplifyCtorLikeReactLynx2: true
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.define.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md) > [define](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.define.md)

## DefineDceVisitorConfig.define property

Replaces variables in your code with other values or expressions at compile time.

**Signature:**

```typescript
define: Record<string, string>
```

## Remarks

Caveat: differences between `source.define`

`defineDCE` happens before transforming `background-only` directives. So it's useful for eliminating code that is only used in the background from main-thread.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      defineDCE: {
        define: {
          __FOO__: 'false',
          'process.env.PLATFORM': '"lynx"',
        },
      },
    })
  ],
})
```

Then, `__FOO__` and `process.env.PLATFORM` could be used in source code.

```
if (process.env.PLATFORM === 'lynx') {
  console.log('lynx')
}

function FooOrBar() {
  if (__FOO__) {
    return <text>foo</text>
  } else {
    return <text>bar</text>
  }
}
```



---
url: /api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md)

## DefineDceVisitorConfig interface

Like `define` in various bundlers, but this one happens at transform time, and a DCE pass will be performed.

**Signature:**

```typescript
export interface DefineDceVisitorConfig 
```

## Properties

| Property                                                                     | Modifiers | Type                    | Description                                                                       |
| ---------------------------------------------------------------------------- | --------- | ----------------------- | --------------------------------------------------------------------------------- |
| [define](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.define.md) |           | Record\<string, string> | Replaces variables in your code with other values or expressions at compile time. |



---
url: /api/rspeedy/react-rsbuild-plugin.extractstrconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md)

## ExtractStrConfig interface

Merge same string literals in JS and Lepus to reduce output bundle size. Set to `false` to disable.

**Signature:**

```typescript
export interface ExtractStrConfig 
```

## Properties

| Property                                                                     | Modifiers | Type   | Description                                            |
| ---------------------------------------------------------------------------- | --------- | ------ | ------------------------------------------------------ |
| [strLength](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.strlength.md) |           | number | The minimum length of string literals to be extracted. |



---
url: /api/rspeedy/react-rsbuild-plugin.extractstrconfig.strlength.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md) > [strLength](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.strlength.md)

## ExtractStrConfig.strLength property

The minimum length of string literals to be extracted.

**Signature:**

```typescript
strLength: number
```

## Remarks

Default value: `20`<!-- -->.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      extractStr: {
        strLength: 10,
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md)

## react-rsbuild-plugin package

A rsbuild plugin that integrates with ReactLynx.

## Functions

| Function                                                                             | Description                            |
| ------------------------------------------------------------------------------------ | -------------------------------------- |
| [pluginReactLynx(userOptions)](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md) | Create a rsbuild plugin for ReactLynx. |

## Interfaces

| Interface                                                                                   | Description                                                                                                             |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md) | Controls whether to add wrapper elements for components                                                                 |
| [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md)             | The <code>compat</code> option controls compatibilities with ReactLynx2.0.                                              |
| [DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md)       | Like <code>define</code> in various bundlers, but this one happens at transform time, and a DCE pass will be performed. |
| [ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md)                   | Merge same string literals in JS and Lepus to reduce output bundle size. Set to <code>false</code> to disable.          |
| [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md)       | Options of [pluginReactLynx()](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)                                    |
| [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md)               | How main-thread code will be shaken.                                                                                    |



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [pluginReactLynx](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)

## pluginReactLynx() function

Create a rsbuild plugin for ReactLynx.

**Signature:**

```typescript
export declare function pluginReactLynx(userOptions?: PluginReactLynxOptions): RsbuildPlugin[];
```

## Parameters

| Parameter   | Type                                                                                  | Description  |
| ----------- | ------------------------------------------------------------------------------------- | ------------ |
| userOptions | [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) | _(Optional)_ |

**Returns:**

RsbuildPlugin\[]

## Example

```ts
// rsbuild.config.ts
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
export default {
  plugins: [pluginReactLynx()]
}
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.compat.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [compat](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.compat.md)

## PluginReactLynxOptions.compat property

The `compat` option controls compatibilities with ReactLynx2.0.

**Signature:**

```typescript
compat?: Partial<CompatVisitorConfig> & {
        disableCreateSelectorQueryIncompatibleWarning?: boolean;
    } | undefined;
```

## Remarks

These options should only be used for migrating from ReactLynx2.0.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [customCSSInheritanceList](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md)

## PluginReactLynxOptions.customCSSInheritanceList property

When [PluginReactLynxOptions.enableCSSInheritance](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md) is enabled, `customCSSInheritanceList` can control which properties are inheritable, not just the default ones.

**Signature:**

```typescript
customCSSInheritanceList?: string[] | undefined;
```

## Example

By setting `customCSSInheritanceList: ['direction', 'overflow']`<!-- -->, only the `direction` and `overflow` properties are inheritable.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
 plugins: [
   pluginReactLynx({
     enableCSSInheritance: true,
     customCSSInheritanceList: ['direction', 'overflow']
   }),
 ],
}
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.debuginfooutside.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [debugInfoOutside](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.debuginfooutside.md)

## PluginReactLynxOptions.debugInfoOutside property

debugInfoOutside controls whether the debug info is placed outside the template.

**Signature:**

```typescript
debugInfoOutside?: boolean;
```

## Remarks

This is recommended to be set to true to reduce template size.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.defaultdisplaylinear.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [defaultDisplayLinear](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.defaultdisplaylinear.md)

## PluginReactLynxOptions.defaultDisplayLinear property

defaultDisplayLinear controls whether the default value of `display` in CSS is `linear`<!-- -->.

**Signature:**

```typescript
defaultDisplayLinear?: boolean;
```

## Remarks

If `defaultDisplayLinear === false`<!-- -->, the default `display` would be `flex` instead of `linear`<!-- -->.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.definedce.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [defineDCE](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.definedce.md)

## PluginReactLynxOptions.defineDCE property

Like `define` in various bundlers, but this one happens at transform time, and a DCE pass will be performed.

**Signature:**

```typescript
defineDCE?: Partial<DefineDceVisitorConfig> | undefined;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableAccessibilityElement](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md)

## PluginReactLynxOptions.enableAccessibilityElement property

enableAccessibilityElement set the default value of `accessibility-element` for all `<view />` elements.

**Signature:**

```typescript
enableAccessibilityElement?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableCSSInheritance](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md)

## PluginReactLynxOptions.enableCSSInheritance property

enableCSSInheritance enables the default inheritance properties.

**Signature:**

```typescript
enableCSSInheritance?: boolean;
```

## Remarks

The following properties are inherited by default:

- `direction`

- `color`

- `font-family`

- `font-size`

- `font-style`

- `font-weight`

- `letter-spacing`

- `line-height`

- `line-spacing`

- `text-align`

- `text-decoration`

- `text-shadow`

It is recommended to use with [PluginReactLynxOptions.customCSSInheritanceList](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md) to avoid performance issues.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinvalidation.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableCSSInvalidation](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinvalidation.md)

## PluginReactLynxOptions.enableCSSInvalidation property

CSS Invalidation refers to the process of determining which elements need to have their styles recalculated when the DOM is updated.

**Signature:**

```typescript
enableCSSInvalidation?: boolean;
```

## Remarks

When using combinator to determine the styles of various elements (including descendants, adjacent siblings, etc.), it is recommended to enable this feature. Otherwise, only the initial class setting can match the corresponding combinator, and subsequent updates will not recalculate the related styles.

We find that collecting invalidation nodes and updating them is a relatively time-consuming process. If there is no such usage and better style matching performance is needed, this feature can be selectively disabled.

## Example

If a descendant selector `.a .b` is defined in a CSS file, then when an element's class changes to `.a`<!-- -->, all nodes in its subtree with the className `.b` need to have their styles recalculated.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssselector.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableCSSSelector](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssselector.md)

## PluginReactLynxOptions.enableCSSSelector property

enableCSSSelector controls whether enabling the new CSS implementation.

**Signature:**

```typescript
enableCSSSelector?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableicu.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableICU](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableicu.md)

## PluginReactLynxOptions.enableICU property

enableICU enables the Intl API to be enabled globally.

If enabled, please double check the compatibility with Lynx Share Context feature to avoid using shared Intl API from other destroyed card.

**Signature:**

```typescript
enableICU?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablenewgesture.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableNewGesture](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablenewgesture.md)

## PluginReactLynxOptions.enableNewGesture property

enableNewGesture enables the new gesture system.

**Signature:**

```typescript
enableNewGesture?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableparallelelement.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableParallelElement](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableparallelelement.md)

## PluginReactLynxOptions.enableParallelElement property

enableParallelElement enables Threaded Element Resolution.

**Signature:**

```typescript
enableParallelElement?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableremovecssscope.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableRemoveCSSScope](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableremovecssscope.md)

## PluginReactLynxOptions.enableRemoveCSSScope property

enableRemoveCSSScope controls whether CSS is restrict to use in the component scope.

`true`<!-- -->: All CSS files are treated as global CSS.

`false`<!-- -->: All CSS files are treated as scoped CSS, and only take effect in the component that explicitly imports it.

`undefined`<!-- -->: Only use scoped CSS for CSS Modules, and treat other CSS files as global CSS. Scoped CSS is faster than global CSS, thus you can use CSS Modules to speedy up your CSS if there are performance issues.

**Signature:**

```typescript
enableRemoveCSSScope?: boolean | undefined;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablessr.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableSSR](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablessr.md)

## PluginReactLynxOptions.enableSSR property

`enableSSR` enable Lynx SSR feature for this build.

**Signature:**

```typescript
enableSSR?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [engineVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md)

## PluginReactLynxOptions.engineVersion property

`engineVersion` specifies the minimum Lynx Engine version required for an App bundle to function properly.

**Signature:**

```typescript
engineVersion?: string;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [experimental\_isLazyBundle](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md)

## PluginReactLynxOptions.experimental\_isLazyBundle property

> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Generate standalone lazy bundle.

**Signature:**

```typescript
experimental_isLazyBundle?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.extractstr.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [extractStr](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.extractstr.md)

## PluginReactLynxOptions.extractStr property

Merge same string literals in JS and Lepus to reduce output bundle size. Set to `false` to disable.

**Signature:**

```typescript
extractStr?: Partial<ExtractStrConfig> | boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.firstscreensynctiming.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [firstScreenSyncTiming](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.firstscreensynctiming.md)

## PluginReactLynxOptions.firstScreenSyncTiming property

This flag controls when MainThread (Lepus) transfers control to Background after the first screen

This flag has two options:

`"immediately"`<!-- -->: Transfer immediately

`"jsReady"`<!-- -->: Transfer when background (JS Runtime) is ready

After handing over control, MainThread (Lepus) runtime can no longer respond to data updates, and data updates will be forwarded to background (JS Runtime) and processed \_\_asynchronously\_\_

**Signature:**

```typescript
firstScreenSyncTiming?: 'immediately' | 'jsReady';
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.jsx.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [jsx](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.jsx.md)

## PluginReactLynxOptions.jsx property

The `jsx` option controls how JSX is transformed.

**Signature:**

```typescript
jsx?: Partial<JsxTransformerConfig> | undefined;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md)

## PluginReactLynxOptions interface

Options of [pluginReactLynx()](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)

**Signature:**

```typescript
export interface PluginReactLynxOptions 
```

## Properties

| Property                                                                                                                    | Modifiers | Type                                                                                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [compat?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.compat.md)                                               |           | Partial\<[CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md)<!-- -->> & \{ disableCreateSelectorQueryIncompatibleWarning?: boolean; } \| undefined | _(Optional)_ The <code>compat</code> option controls compatibilities with ReactLynx2.0.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [customCSSInheritanceList?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md)           |           | string\[] \| undefined                                                                                                                                                         | _(Optional)_ When [PluginReactLynxOptions.enableCSSInheritance](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md) is enabled, <code>customCSSInheritanceList</code> can control which properties are inheritable, not just the default ones.                                                                                                                                                                                                                                                                          |
| [debugInfoOutside?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.debuginfooutside.md)                           |           | boolean                                                                                                                                                                        | _(Optional)_ debugInfoOutside controls whether the debug info is placed outside the template.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [defaultDisplayLinear?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.defaultdisplaylinear.md)                   |           | boolean                                                                                                                                                                        | _(Optional)_ defaultDisplayLinear controls whether the default value of <code>display</code> in CSS is <code>linear</code>.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [defineDCE?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.definedce.md)                                         |           | Partial\<[DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md)<!-- -->> \| undefined                                                           | _(Optional)_ Like <code>define</code> in various bundlers, but this one happens at transform time, and a DCE pass will be performed.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [enableAccessibilityElement?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md)       |           | boolean                                                                                                                                                                        | _(Optional)_ enableAccessibilityElement set the default value of <code>accessibility-element</code> for all <code>\<view /></code> elements.                                                                                                                                                                                                                                                                                                                                                                                                          |
| [enableCSSInheritance?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md)                   |           | boolean                                                                                                                                                                        | _(Optional)_ enableCSSInheritance enables the default inheritance properties.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [enableCSSInvalidation?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinvalidation.md)                 |           | boolean                                                                                                                                                                        | _(Optional)_ CSS Invalidation refers to the process of determining which elements need to have their styles recalculated when the DOM is updated.                                                                                                                                                                                                                                                                                                                                                                                                     |
| [enableCSSSelector?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssselector.md)                         |           | boolean                                                                                                                                                                        | _(Optional)_ enableCSSSelector controls whether enabling the new CSS implementation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [enableICU?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableicu.md)                                         |           | boolean                                                                                                                                                                        | <p>_(Optional)_ enableICU enables the Intl API to be enabled globally.</p><p>If enabled, please double check the compatibility with Lynx Share Context feature to avoid using shared Intl API from other destroyed card.</p>                                                                                                                                                                                                                                                                                                                          |
| [enableNewGesture?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablenewgesture.md)                           |           | boolean                                                                                                                                                                        | _(Optional)_ enableNewGesture enables the new gesture system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [enableParallelElement?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableparallelelement.md)                 |           | boolean                                                                                                                                                                        | _(Optional)_ enableParallelElement enables Threaded Element Resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [enableRemoveCSSScope?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableremovecssscope.md)                   |           | boolean \| undefined                                                                                                                                                           | <p>_(Optional)_ enableRemoveCSSScope controls whether CSS is restrict to use in the component scope.</p><p><code>true</code>: All CSS files are treated as global CSS.</p><p><code>false</code>: All CSS files are treated as scoped CSS, and only take effect in the component that explicitly imports it.</p><p><code>undefined</code>: Only use scoped CSS for CSS Modules, and treat other CSS files as global CSS. Scoped CSS is faster than global CSS, thus you can use CSS Modules to speedy up your CSS if there are performance issues.</p> |
| [enableSSR?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablessr.md)                                         |           | boolean                                                                                                                                                                        | _(Optional)_ <code>enableSSR</code> enable Lynx SSR feature for this build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [engineVersion?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md)                                 |           | string                                                                                                                                                                         | _(Optional)_ <code>engineVersion</code> specifies the minimum Lynx Engine version required for an App bundle to function properly.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [experimental\_isLazyBundle?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md)        |           | boolean                                                                                                                                                                        | **_(ALPHA)_** _(Optional)_ Generate standalone lazy bundle.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [extractStr?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.extractstr.md)                                       |           | Partial\<[ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md)<!-- -->> \| boolean                                                                         | _(Optional)_ Merge same string literals in JS and Lepus to reduce output bundle size. Set to <code>false</code> to disable.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [firstScreenSyncTiming?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.firstscreensynctiming.md)                 |           | 'immediately' \| 'jsReady'                                                                                                                                                     | <p>_(Optional)_ This flag controls when MainThread (Lepus) transfers control to Background after the first screen</p><p>This flag has two options:</p><p><code>"immediately"</code>: Transfer immediately</p><p><code>"jsReady"</code>: Transfer when background (JS Runtime) is ready</p><p>After handing over control, MainThread (Lepus) runtime can no longer respond to data updates, and data updates will be forwarded to background (JS Runtime) and processed \_\_asynchronously\_\_</p>                                                     |
| [pipelineSchedulerConfig?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.pipelineschedulerconfig.md)             |           | number                                                                                                                                                                         | _(Optional)_ Composite configuration representing pipeline scheduling strategies, including [PluginReactLynxOptions.enableParallelElement](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableparallelelement.md) and list batch-rendering. All newly introduced scheduling strategies will be managed by this uint64 configuration.                                                                                                                                                                                                      |
| [removeDescendantSelectorScope?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.removedescendantselectorscope.md) |           | boolean                                                                                                                                                                        | _(Optional)_ removeDescendantSelectorScope is used to remove the scope of descendant selectors.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [shake?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.shake.md)                                                 |           | Partial\<[ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md)<!-- -->> \| undefined                                                                   | _(Optional)_ How main-thread code will be shaken.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [targetSdkVersion?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md)                           |           | string                                                                                                                                                                         | _(Optional)_ targetSdkVersion is used to specify the minimal Lynx Engine version that a App bundle can run on.                                                                                                                                                                                                                                                                                                                                                                                                                                        |



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.pipelineschedulerconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [pipelineSchedulerConfig](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.pipelineschedulerconfig.md)

## PluginReactLynxOptions.pipelineSchedulerConfig property

Composite configuration representing pipeline scheduling strategies, including [PluginReactLynxOptions.enableParallelElement](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableparallelelement.md) and list batch-rendering. All newly introduced scheduling strategies will be managed by this uint64 configuration.

**Signature:**

```typescript
pipelineSchedulerConfig?: number;
```

## Remarks

Preallocate 64 bit unsigned integer for pipeline scheduler config.

- 0 \~ 7 bit: Reserved for parsing binary bundle into C++ bundle.

- 8 \~ 15 bit: Reserved for MTS Render.

- 16 \~ 23 bit: Reserved for resolve stage in Pixel Pipeline.

- 24 \~ 31 bit: Reserved for layout stage in Pixel Pipeline.

- 32 \~ 39 bit: Reserved for execute UI OP stage in Pixel Pipeline.

- 40 \~ 47 bit: Reserved for paint stage in Pixel Pipeline.

- 48 \~ 63 bit: Flexible bits for extensibility.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.removedescendantselectorscope.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [removeDescendantSelectorScope](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.removedescendantselectorscope.md)

## PluginReactLynxOptions.removeDescendantSelectorScope property

removeDescendantSelectorScope is used to remove the scope of descendant selectors.

**Signature:**

```typescript
removeDescendantSelectorScope?: boolean;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.shake.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [shake](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.shake.md)

## PluginReactLynxOptions.shake property

How main-thread code will be shaken.

**Signature:**

```typescript
shake?: Partial<ShakeVisitorConfig> | undefined;
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [targetSdkVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md)

## PluginReactLynxOptions.targetSdkVersion property

> Warning: This API is now obsolete.
>
> `targetSdkVersion` is now an alias of [PluginReactLynxOptions.engineVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md)<!-- -->. Use [PluginReactLynxOptions.engineVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md) instead.

targetSdkVersion is used to specify the minimal Lynx Engine version that a App bundle can run on.

**Signature:**

```typescript
targetSdkVersion?: string;
```



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md)

## ShakeVisitorConfig interface

How main-thread code will be shaken.

**Signature:**

```typescript
export interface ShakeVisitorConfig 
```

## Properties

| Property                                                                                     | Modifiers | Type           | Description                                                             |
| -------------------------------------------------------------------------------------------- | --------- | -------------- | ----------------------------------------------------------------------- |
| [pkgName](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.pkgname.md)                   |           | Array\<string> | Package names to identify runtime imports that need to be processed     |
| [removeCallParams](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecallparams.md) |           | Array\<string> | Function names whose parameters should be removed during transformation |
| [retainProp](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.retainprop.md)             |           | Array\<string> | Properties that should be retained in the component class               |



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.pkgname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md) > [pkgName](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.pkgname.md)

## ShakeVisitorConfig.pkgName property

Package names to identify runtime imports that need to be processed

**Signature:**

```typescript
pkgName: Array<string>
```

## Remarks

Default value: `['@lynx-js/react-runtime']` The provided values will be merged with the default values instead of replacing them.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        pkgName: ['@lynx-js/react-runtime']
      }
    })
  ]
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecallparams.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md) > [removeCallParams](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecallparams.md)

## ShakeVisitorConfig.removeCallParams property

Function names whose parameters should be removed during transformation

**Signature:**

```typescript
removeCallParams: Array<string>
```

## Remarks

Default value: `['useEffect', 'useLayoutEffect', '__runInJS', 'useLynxGlobalEventListener', 'useImperativeHandle']` The provided values will be merged with the default values instead of replacing them.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        removeCallParams: ['useMyCustomEffect']
      }
    })
  ]
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.retainprop.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md) > [retainProp](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.retainprop.md)

## ShakeVisitorConfig.retainProp property

Properties that should be retained in the component class

**Signature:**

```typescript
retainProp: Array<string>
```

## Remarks

Default value: `['constructor', 'render', 'getDerivedStateFromProps', 'state', 'defaultDataProcessor', 'dataProcessors', 'contextType', 'defaultProps']` The provided values will be merged with the default values instead of replacing them.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        retainProp: ['myCustomMethod']
      }
    })
  ]
})
```



---
url: /api/rspeedy/rspeedy.buildcache.builddependencies.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md) > [buildDependencies](/api/rspeedy/rspeedy.buildcache.builddependencies.md)

## BuildCache.buildDependencies property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

An array of files containing build dependencies. Rspack will use the hash of each of these files to invalidate the persistent cache.

**Signature:**

```typescript
buildDependencies?: string[] | undefined;
```

## Remarks

Rspeedy will use the following configuration files as the default build dependencies:

- `package.json`

- `tsconfig.json` (or `source.tsconfigPath`<!-- -->)

- `.env`<!-- -->, `.env.*`

- `tailwindcss.config.*`

When using Rspeedy CLI, it will also automatically add `lynx.config.js` to the build dependencies.

## Example

Add `postcss.config.js` to the build dependencies.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: {
      buildDependencies: ['postcss.config.js'],
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.buildcache.cachedigest.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md) > [cacheDigest](/api/rspeedy/rspeedy.buildcache.cachedigest.md)

## BuildCache.cacheDigest property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Add additional cache digests, the previous build cache will be invalidated when any value in the array changes.

**Signature:**

```typescript
cacheDigest?: Array<string | undefined> | undefined;
```

## Example

Add `process.env.SOME_ENV` to the cache digest.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: {
      cacheDigest: [process.env.SOME_ENV],
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.buildcache.cachedirectory.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md) > [cacheDirectory](/api/rspeedy/rspeedy.buildcache.cachedirectory.md)

## BuildCache.cacheDirectory property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

The output directory of the cache files.

**Signature:**

```typescript
cacheDirectory?: string | undefined;
```



---
url: /api/rspeedy/rspeedy.buildcache.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md)

## BuildCache interface

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Enable or configure persistent build cache.

This feature is experimental and may be changed in the future.

**Signature:**

```typescript
export interface BuildCache 
```

## Properties

| Property                                                                   | Modifiers | Type                                     | Description                                                                                                                                                    |
| -------------------------------------------------------------------------- | --------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [buildDependencies?](/api/rspeedy/rspeedy.buildcache.builddependencies.md) |           | string\[] \| undefined                   | **_(BETA)_** _(Optional)_ An array of files containing build dependencies. Rspack will use the hash of each of these files to invalidate the persistent cache. |
| [cacheDigest?](/api/rspeedy/rspeedy.buildcache.cachedigest.md)             |           | Array\<string \| undefined> \| undefined | **_(BETA)_** _(Optional)_ Add additional cache digests, the previous build cache will be invalidated when any value in the array changes.                      |
| [cacheDirectory?](/api/rspeedy/rspeedy.buildcache.cachedirectory.md)       |           | string \| undefined                      | **_(BETA)_** _(Optional)_ The output directory of the cache files.                                                                                             |



---
url: /api/rspeedy/rspeedy.chunksplit.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md)

## ChunkSplit interface

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplit 
```

## Properties

| Property                                                 | Modifiers | Type                                                                                                   | Description                                                         |
| -------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [override?](/api/rspeedy/rspeedy.chunksplit.override.md) |           | Rspack.Configuration extends \{ optimization?: \{ splitChunks?: infer P; } \| undefined; } ? P : never | _(Optional)_ Custom Rspack chunk splitting config can be specified. |
| [strategy?](/api/rspeedy/rspeedy.chunksplit.strategy.md) |           | 'all-in-one' \| 'split-by-module' \| 'split-by-experience' \| 'single-vendor' \| undefined             | _(Optional)_ The ChunkSplitting strategy.                           |



---
url: /api/rspeedy/rspeedy.chunksplit.override.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md) > [override](/api/rspeedy/rspeedy.chunksplit.override.md)

## ChunkSplit.override property

Custom Rspack chunk splitting config can be specified.

**Signature:**

```typescript
override?: Rspack.Configuration extends {
        optimization?: {
            splitChunks?: infer P;
        } | undefined;
    } ? P : never;
```

## Example

- Split `@lynx-js/react` and `react-router` into chunk `lib-react`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'split-by-experience',
      override: {
        cacheGroups: {
          react: {
            test: /node_modules[\\/](@lynx-js[\\/]react|react-router)[\\/]/,
            name: 'lib-react',
          },
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplit.strategy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md) > [strategy](/api/rspeedy/rspeedy.chunksplit.strategy.md)

## ChunkSplit.strategy property

The ChunkSplitting strategy.

**Signature:**

```typescript
strategy?: 'all-in-one' | 'split-by-module' | 'split-by-experience' | 'single-vendor' | undefined;
```

## Remarks

- `split-by-experience`<!-- -->(default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.

- `split-by-module`<!-- -->: split by NPM package granularity, each NPM package corresponds to a chunk.

- `split-by-size`<!-- -->: automatically split according to module size.

- `all-in-one`<!-- -->: bundle all codes into one chunk.

- `single-vendor`<!-- -->: bundle all NPM packages into a single chunk.

- `custom`<!-- -->: custom chunk splitting strategy.

## Example 1

- Use `all-in-one` to put all modules in one chunk.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'all-in-one',
    },
  },
})
```

## Example 2

- Use `single-vendor` to put all third-party dependencies in one chunk. And source code in another chunk.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'single-vendor',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplitbysize.maxsize.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [maxSize](/api/rspeedy/rspeedy.chunksplitbysize.maxsize.md)

## ChunkSplitBySize.maxSize property

The maximum size of a chunk, unit in bytes. Defaults to `Number.POSITIVE_INFINITY`<!-- -->.

**Signature:**

```typescript
maxSize?: number | undefined;
```

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      maxSize: 50000,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplitbysize.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md)

## ChunkSplitBySize interface

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplitBySize 
```

## Properties

| Property                                                       | Modifiers | Type                                                                                                   | Description                                                                                                  |
| -------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| [maxSize?](/api/rspeedy/rspeedy.chunksplitbysize.maxsize.md)   |           | number \| undefined                                                                                    | _(Optional)_ The maximum size of a chunk, unit in bytes. Defaults to <code>Number.POSITIVE\_INFINITY</code>. |
| [minSize?](/api/rspeedy/rspeedy.chunksplitbysize.minsize.md)   |           | number \| undefined                                                                                    | _(Optional)_ The minimum size of a chunk, unit in bytes. Defaults to <code>10000</code>.                     |
| [override?](/api/rspeedy/rspeedy.chunksplitbysize.override.md) |           | Rspack.Configuration extends \{ optimization?: \{ splitChunks?: infer P; } \| undefined; } ? P : never | _(Optional)_ Custom Rspack chunk splitting config can be specified.                                          |
| [strategy](/api/rspeedy/rspeedy.chunksplitbysize.strategy.md)  |           | 'split-by-size'                                                                                        | The ChunkSplitting strategy.                                                                                 |



---
url: /api/rspeedy/rspeedy.chunksplitbysize.minsize.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [minSize](/api/rspeedy/rspeedy.chunksplitbysize.minsize.md)

## ChunkSplitBySize.minSize property

The minimum size of a chunk, unit in bytes. Defaults to `10000`<!-- -->.

**Signature:**

```typescript
minSize?: number | undefined;
```

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      minSize: 20000,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplitbysize.override.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [override](/api/rspeedy/rspeedy.chunksplitbysize.override.md)

## ChunkSplitBySize.override property

Custom Rspack chunk splitting config can be specified.

**Signature:**

```typescript
override?: Rspack.Configuration extends {
        optimization?: {
            splitChunks?: infer P;
        } | undefined;
    } ? P : never;
```



---
url: /api/rspeedy/rspeedy.chunksplitbysize.strategy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [strategy](/api/rspeedy/rspeedy.chunksplitbysize.strategy.md)

## ChunkSplitBySize.strategy property

The ChunkSplitting strategy.

**Signature:**

```typescript
strategy: 'split-by-size';
```

## Remarks

- `split-by-experience`<!-- -->(default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.

- `split-by-module`<!-- -->: split by NPM package granularity, each NPM package corresponds to a chunk.

- `split-by-size`<!-- -->: automatically split according to module size.

- `all-in-one`<!-- -->: bundle all codes into one chunk.

- `single-vendor`<!-- -->: bundle all NPM packages into a single chunk.

- `custom`<!-- -->: custom chunk splitting strategy.



---
url: /api/rspeedy/rspeedy.chunksplitcustom.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md)

## ChunkSplitCustom interface

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplitCustom 
```

## Properties

| Property                                                             | Modifiers | Type                                                                                                   | Description                                                         |
| -------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [splitChunks?](/api/rspeedy/rspeedy.chunksplitcustom.splitchunks.md) |           | Rspack.Configuration extends \{ optimization?: \{ splitChunks?: infer P; } \| undefined; } ? P : never | _(Optional)_ Custom Rspack chunk splitting config can be specified. |
| [strategy](/api/rspeedy/rspeedy.chunksplitcustom.strategy.md)        |           | 'custom'                                                                                               | The ChunkSplitting strategy.                                        |



---
url: /api/rspeedy/rspeedy.chunksplitcustom.splitchunks.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md) > [splitChunks](/api/rspeedy/rspeedy.chunksplitcustom.splitchunks.md)

## ChunkSplitCustom.splitChunks property

Custom Rspack chunk splitting config can be specified.

**Signature:**

```typescript
splitChunks?: Rspack.Configuration extends {
        optimization?: {
            splitChunks?: infer P;
        } | undefined;
    } ? P : never;
```

## Example

- Split `@lynx-js/react` and `react-router` into chunk `lib-react`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'custom',
      splitChunks: {
        cacheGroups: {
          react: {
            test: /node_modules[\\/](@lynx-js[\\/]react|react-router)[\\/]/,
            name: 'lib-react',
          },
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplitcustom.strategy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md) > [strategy](/api/rspeedy/rspeedy.chunksplitcustom.strategy.md)

## ChunkSplitCustom.strategy property

The ChunkSplitting strategy.

**Signature:**

```typescript
strategy: 'custom';
```

## Remarks

- `split-by-experience`<!-- -->(default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.

- `split-by-module`<!-- -->: split by NPM package granularity, each NPM package corresponds to a chunk.

- `split-by-size`<!-- -->: automatically split according to module size.

- `all-in-one`<!-- -->: bundle all codes into one chunk.

- `single-vendor`<!-- -->: bundle all NPM packages into a single chunk.

- `custom`<!-- -->: custom chunk splitting strategy.



---
url: /api/rspeedy/rspeedy.config.dev.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [dev](/api/rspeedy/rspeedy.config.dev.md)

## Config.dev property

The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc.

**Signature:**

```typescript
dev?: Dev | undefined;
```



---
url: /api/rspeedy/rspeedy.config.environments.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [environments](/api/rspeedy/rspeedy.config.environments.md)

## Config.environments property

The [Config.environments](/api/rspeedy/rspeedy.config.environments.md) option is used to set the output environment.

**Signature:**

```typescript
environments?: RsbuildConfig['environments'] | undefined;
```

## Remarks

Normally you don't need this if you are not using Lynx for Web.

## Example 1

- Using different entries for Lynx and Web.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  environments: {
    lynx: {},
    web: {
      source: { entry: { web: './src/index.web.jsx' } },
    },
  },
  source: {
    entry: './src/index.jsx',
  },
})
```

## Example 2

- Building Web-only outputs.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  environments: {
    web: {
      source: { entry: { web: './src/index.web.jsx' } },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.config.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md)

## Config interface

The `Config` is the configuration that `rspeedy` uses.

**Signature:**

```typescript
export interface Config 
```

## Properties

| Property                                                     | Modifiers | Type                                                            | Description                                                                                                                                          |
| ------------------------------------------------------------ | --------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| [dev?](/api/rspeedy/rspeedy.config.dev.md)                   |           | [Dev](/api/rspeedy/rspeedy.dev.md) \| undefined                 | _(Optional)_ The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc. |
| [environments?](/api/rspeedy/rspeedy.config.environments.md) |           | RsbuildConfig\['environments'] \| undefined                     | _(Optional)_ The [Config.environments](/api/rspeedy/rspeedy.config.environments.md) option is used to set the output environment.                    |
| [mode?](/api/rspeedy/rspeedy.config.mode.md)                 |           | 'development' \| 'production' \| 'none' \| undefined            | _(Optional)_ Specify the build mode for Rsbuild and Rspack, as each mode has different default behavior and optimizations.                           |
| [output?](/api/rspeedy/rspeedy.config.output.md)             |           | [Output](/api/rspeedy/rspeedy.output.md) \| undefined           | _(Optional)_ The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.                  |
| [performance?](/api/rspeedy/rspeedy.config.performance.md)   |           | [Performance](/api/rspeedy/rspeedy.performance.md) \| undefined | _(Optional)_ The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.               |
| [plugins?](/api/rspeedy/rspeedy.config.plugins.md)           |           | RsbuildPlugins \| undefined                                     | _(Optional)_ The <code>plugins</code> option is used to customize the build process in a variety of ways.                                            |
| [resolve?](/api/rspeedy/rspeedy.config.resolve.md)           |           | [Resolve](/api/rspeedy/rspeedy.resolve.md) \| undefined         | _(Optional)_ The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.                             |
| [server?](/api/rspeedy/rspeedy.config.server.md)             |           | [Server](/api/rspeedy/rspeedy.server.md) \| undefined           | _(Optional)_ The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.                                                 |
| [source?](/api/rspeedy/rspeedy.config.source.md)             |           | [Source](/api/rspeedy/rspeedy.source.md) \| undefined           | _(Optional)_ The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.                                               |
| [tools?](/api/rspeedy/rspeedy.config.tools.md)               |           | [Tools](/api/rspeedy/rspeedy.tools.md) \| undefined             | _(Optional)_ The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.                                      |



---
url: /api/rspeedy/rspeedy.config.mode.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [mode](/api/rspeedy/rspeedy.config.mode.md)

## Config.mode property

Specify the build mode for Rsbuild and Rspack, as each mode has different default behavior and optimizations.

**Signature:**

```typescript
mode?: 'development' | 'production' | 'none' | undefined;
```

## Remarks

The default value of mode depends on the `process.env.NODE_ENV` environment variable:

- If `NODE_ENV` is production, the default value is production.

- If `NODE_ENV` is development, the default value is development.

- If `NODE_ENV` has any other value, the default value is none.

- If you set the value of mode, the value of `NODE_ENV` will be ignored.

When using Rspeedy's CLI:

- `rspeedy dev` and `rspeedy preview` will set the default values of `NODE_ENV` and `mode` to `'development'`<!-- -->.

- `rspeedy build` will set the default values of `NODE_ENV` and `mode` to `'production'`<!-- -->.

## Example 1

If the value of `mode` is `'development'`<!-- -->:

- Enable HMR and register the [HotModuleReplacementPlugin](https://rspack.dev/plugins/webpack/hot-module-replacement-plugin)<!-- -->.

- Generate JavaScript source maps, but do not generate CSS source maps. See [Output.sourceMap](/api/rspeedy/rspeedy.output.sourcemap.md) for details.

- The `process.env.NODE_ENV` in the source code will be replaced with `'development'`<!-- -->.

- The `import.meta.env.MODE` in the source code will be replaced with `'development'`<!-- -->.

- The `import.meta.env.DEV` in the source code will be replaced with `true`<!-- -->.

- The `import.meta.env.PROD` in the source code will be replaced with `false`<!-- -->.

## Example 2

If the value of `mode` is `'production'`<!-- -->:

- Enable JavaScript code minification and register the [SwcJsMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin)<!-- -->.

- Generated JavaScript and CSS filenames will have hash suffixes, see [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md)<!-- -->.

- Generated CSS Modules classnames will be shorter, see [CssModules.localIdentName](/api/rspeedy/rspeedy.cssmodules.localidentname.md)<!-- -->.

- Do not generate JavaScript and CSS source maps, see [Output.sourceMap](/api/rspeedy/rspeedy.output.sourcemap.md)<!-- -->.

- The `process.env.NODE_ENV` in the source code will be replaced with `'production'`<!-- -->.

- The `import.meta.env.MODE` in the source code will be replaced with `'production'`<!-- -->.

- The `import.meta.env.DEV` in the source code will be replaced with `false`<!-- -->.

- The `import.meta.env.PROD` in the source code will be replaced with `true`<!-- -->.



---
url: /api/rspeedy/rspeedy.config.output.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [output](/api/rspeedy/rspeedy.config.output.md)

## Config.output property

The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.

**Signature:**

```typescript
output?: Output | undefined;
```



---
url: /api/rspeedy/rspeedy.config.performance.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [performance](/api/rspeedy/rspeedy.config.performance.md)

## Config.performance property

The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.

**Signature:**

```typescript
performance?: Performance | undefined;
```



---
url: /api/rspeedy/rspeedy.config.plugins.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [plugins](/api/rspeedy/rspeedy.config.plugins.md)

## Config.plugins property

The `plugins` option is used to customize the build process in a variety of ways.

**Signature:**

```typescript
plugins?: RsbuildPlugins | undefined;
```

## Remarks

Rspeedy use the plugin APIs from [Rsbuild](https://rsbuild.dev/plugins/dev/index)<!-- -->. See the corresponding document for developing a plugin.



---
url: /api/rspeedy/rspeedy.config.provider.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [provider](/api/rspeedy/rspeedy.config.provider.md)

## Config.provider property

> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

The Rsbuild provider.

**Signature:**

```typescript
provider?: RsbuildConfig['provider'];
```

## Example

You can switch from Rspack to Webpack by:

- Use `webpackProvider` from `@rsbuild/webpack` - Add `pluginSwc` from `@rsbuild/plugin-webpack-swc` for TypeScript transpilation

```ts
import { defineConfig } from '@lynx-js/rspeedy'
import { webpackProvider } from '@rsbuild/webpack'
import { pluginSwc } from '@rsbuild/plugin-webpack-swc'

export default defineConfig({
  provider: webpackProvider,
  plugins: [
    pluginSwc(),
  ],
})
```



---
url: /api/rspeedy/rspeedy.config.resolve.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [resolve](/api/rspeedy/rspeedy.config.resolve.md)

## Config.resolve property

The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.

**Signature:**

```typescript
resolve?: Resolve | undefined;
```



---
url: /api/rspeedy/rspeedy.config.server.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [server](/api/rspeedy/rspeedy.config.server.md)

## Config.server property

The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.

**Signature:**

```typescript
server?: Server | undefined;
```



---
url: /api/rspeedy/rspeedy.config.source.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [source](/api/rspeedy/rspeedy.config.source.md)

## Config.source property

The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.

**Signature:**

```typescript
source?: Source | undefined;
```



---
url: /api/rspeedy/rspeedy.config.tools.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [tools](/api/rspeedy/rspeedy.config.tools.md)

## Config.tools property

The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.

**Signature:**

```typescript
tools?: Tools | undefined;
```



---
url: /api/rspeedy/rspeedy.configparams.command.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConfigParams](/api/rspeedy/rspeedy.configparams.md) > [command](/api/rspeedy/rspeedy.configparams.command.md)

## ConfigParams.command property

The CLI command of Rspeedy.

**Signature:**

```typescript
command: 'build' | 'dev' | 'inspect' | 'preview' | (string & Record<never, never>);
```

## Remarks

Possible values:

- `'build'`

- `'dev'`

- `'inspect'`

- `'preview'`



---
url: /api/rspeedy/rspeedy.configparams.env.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConfigParams](/api/rspeedy/rspeedy.configparams.md) > [env](/api/rspeedy/rspeedy.configparams.env.md)

## ConfigParams.env property

The value of `process.env['NODE_ENV']`

**Signature:**

```typescript
env: 'production' | 'development' | 'test' | (string & Record<never, never>);
```

## Remarks

Common values include (non-exhaustive): - `'production'`

- `'development'`

- `'test'`



---
url: /api/rspeedy/rspeedy.configparams.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConfigParams](/api/rspeedy/rspeedy.configparams.md)

## ConfigParams interface

Parameters for the function exported from `lynx.config.js`<!-- -->.

**Signature:**

```typescript
export interface ConfigParams 
```

## Properties

| Property                                                | Modifiers | Type                                                                           | Description                                         |
| ------------------------------------------------------- | --------- | ------------------------------------------------------------------------------ | --------------------------------------------------- |
| [command](/api/rspeedy/rspeedy.configparams.command.md) |           | 'build' \| 'dev' \| 'inspect' \| 'preview' \| (string & Record\<never, never>) | The CLI command of Rspeedy.                         |
| [env](/api/rspeedy/rspeedy.configparams.env.md)         |           | 'production' \| 'development' \| 'test' \| (string & Record\<never, never>)    | The value of <code>process.env\['NODE\_ENV']</code> |



---
url: /api/rspeedy/rspeedy.consoletype.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConsoleType](/api/rspeedy/rspeedy.consoletype.md)

## ConsoleType type

The type of the console method.

**Signature:**

```typescript
export type ConsoleType = 'log' | 'warn' | 'error' | 'info' | 'debug' | 'profile' | 'profileEnd' | (string & Record<never, never>);
```



---
url: /api/rspeedy/rspeedy.createrspeedy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [createRspeedy](/api/rspeedy/rspeedy.createrspeedy.md)

## createRspeedy() function

The `createRspeedy` method can let you create a Rspeedy instance and you can customize the build or development process in Node.js Runtime.

**Signature:**

```typescript
export declare function createRspeedy({ cwd, rspeedyConfig, loadEnv, environment, callerName, }: CreateRspeedyOptions): Promise<RspeedyInstance>;
```

## Parameters

| Parameter                                                  | Type                                                                 | Description |
| ---------------------------------------------------------- | -------------------------------------------------------------------- | ----------- |
| \{ cwd, rspeedyConfig, loadEnv, environment, callerName, } | [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) |             |

**Returns:**

Promise\<[RspeedyInstance](/api/rspeedy/rspeedy.rspeedyinstance.md)<!-- -->>

- Rspeedy instance.

## Example

```ts
import { createRspeedy } from '@lynx-js/rspeedy'

void async function () {
  const rspeedy = await createRspeedy({})
  await rspeedy.build()
}()
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.callername.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [callerName](/api/rspeedy/rspeedy.createrspeedyoptions.callername.md)

## CreateRspeedyOptions.callerName property

The name of the framework or tool that is currently invoking Rsbuild. This allows plugins to tailor their behavior based on the calling context.

**Signature:**

```typescript
callerName?: string;
```

## Example

Rsbuild plugins can access this value via `api.context.callerName`<!-- -->.

```js
export function myPlugin() {
  return {
    name: 'my-plugin',
    setup(api) {
      // Log the name of the tool invoking Rsbuild
      console.log(`Called by: ${api.context.callerName}`);

      // Conditionally apply plugin logic based on caller
      if (api.context.callerName === 'rspeedy') {
        api.modifyRsbuildConfig((config) => {
          // Apply rspeedy-specific config changes
          return config;
        });
      } else if (api.context.callerName === 'rslib') {
        api.modifyRsbuildConfig((config) => {
          // Apply rslib-specific config changes
          return config;
        });
      }
    }
  };
}
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.cwd.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [cwd](/api/rspeedy/rspeedy.createrspeedyoptions.cwd.md)

## CreateRspeedyOptions.cwd property

The root path of the current build.

**Signature:**

```typescript
cwd?: string;
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.environment.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [environment](/api/rspeedy/rspeedy.createrspeedyoptions.environment.md)

## CreateRspeedyOptions.environment property

Only build specified environments. For example, passing `['lynx']` will only build the `lynx` environment. If not specified or passing an empty array, all environments will be built.

**Signature:**

```typescript
environment?: CreateRsbuildOptions['environment'];
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.loadenv.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [loadEnv](/api/rspeedy/rspeedy.createrspeedyoptions.loadenv.md)

## CreateRspeedyOptions.loadEnv property

Rspeedy automatically loads the .env file by default, utilizing the \[Rsbuild API]\([https://rsbuild.dev/api/javascript-api/core\\#load-env-variables](https://rsbuild.dev/api/javascript-api/core\\#load-env-variables)). You can use the environment variables defined in the .env file within your code by accessing them via `import.meta.env.FOO` or `process.env.Foo`<!-- -->.

**Signature:**

```typescript
loadEnv?: CreateRsbuildOptions['loadEnv'];
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md)

## CreateRspeedyOptions interface

The options of `createRspeedy` method.

**Signature:**

```typescript
export interface CreateRspeedyOptions 
```

## Properties

| Property                                                                     | Modifiers | Type                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------- | --------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [callerName?](/api/rspeedy/rspeedy.createrspeedyoptions.callername.md)       |           | string                                   | _(Optional)_ The name of the framework or tool that is currently invoking Rsbuild. This allows plugins to tailor their behavior based on the calling context.                                                                                                                                                                                                                                                   |
| [cwd?](/api/rspeedy/rspeedy.createrspeedyoptions.cwd.md)                     |           | string                                   | _(Optional)_ The root path of the current build.                                                                                                                                                                                                                                                                                                                                                                |
| [environment?](/api/rspeedy/rspeedy.createrspeedyoptions.environment.md)     |           | CreateRsbuildOptions\['environment']     | _(Optional)_ Only build specified environments. For example, passing <code>\['lynx']</code> will only build the <code>lynx</code> environment. If not specified or passing an empty array, all environments will be built.                                                                                                                                                                                      |
| [loadEnv?](/api/rspeedy/rspeedy.createrspeedyoptions.loadenv.md)             |           | CreateRsbuildOptions\['loadEnv']         | _(Optional)_ Rspeedy automatically loads the .env file by default, utilizing the \[Rsbuild API]\([https://rsbuild.dev/api/javascript-api/core\\#load-env-variables](https://rsbuild.dev/api/javascript-api/core\\#load-env-variables)). You can use the environment variables defined in the .env file within your code by accessing them via <code>import.meta.env.FOO</code> or <code>process.env.Foo</code>. |
| [rspeedyConfig?](/api/rspeedy/rspeedy.createrspeedyoptions.rspeedyconfig.md) |           | [Config](/api/rspeedy/rspeedy.config.md) | _(Optional)_ The config of Rspeedy.                                                                                                                                                                                                                                                                                                                                                                             |



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.rspeedyconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [rspeedyConfig](/api/rspeedy/rspeedy.createrspeedyoptions.rspeedyconfig.md)

## CreateRspeedyOptions.rspeedyConfig property

The config of Rspeedy.

**Signature:**

```typescript
rspeedyConfig?: Config;
```



---
url: /api/rspeedy/rspeedy.cssextract.loaderoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtract](/api/rspeedy/rspeedy.cssextract.md) > [loaderOptions](/api/rspeedy/rspeedy.cssextract.loaderoptions.md)

## CssExtract.loaderOptions property

The options of CSS extract loader.

**Signature:**

```typescript
loaderOptions?: CssExtractRspackLoaderOptions | undefined;
```



---
url: /api/rspeedy/rspeedy.cssextract.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtract](/api/rspeedy/rspeedy.cssextract.md)

## CssExtract interface

The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin)

**Signature:**

```typescript
export interface CssExtract
```

## Properties

| Property                                                           | Modifiers | Type                                                                                                | Description                                                                                                        |
| ------------------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [loaderOptions?](/api/rspeedy/rspeedy.cssextract.loaderoptions.md) |           | [CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md) \| undefined | _(Optional)_ The options of CSS extract loader.                                                                    |
| [pluginOptions?](/api/rspeedy/rspeedy.cssextract.pluginoptions.md) |           | [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md) \| undefined | _(Optional)_ The options for [CssExtractRspackPlugin](https://rspack.dev/plugins/rspack/css-extract-rspack-plugin) |



---
url: /api/rspeedy/rspeedy.cssextract.pluginoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtract](/api/rspeedy/rspeedy.cssextract.md) > [pluginOptions](/api/rspeedy/rspeedy.cssextract.pluginoptions.md)

## CssExtract.pluginOptions property

The options for [CssExtractRspackPlugin](https://rspack.dev/plugins/rspack/css-extract-rspack-plugin)

**Signature:**

```typescript
pluginOptions?: CssExtractRspackPluginOptions | undefined;
```



---
url: /api/rspeedy/rspeedy.cssextractrspackloaderoptions.esmodule.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md) > [esModule](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.esmodule.md)

## CssExtractRspackLoaderOptions.esModule property

The same as [https://github.com/webpack-contrib/mini-css-extract-plugin#esModule](https://github.com/webpack-contrib/mini-css-extract-plugin#esModule)<!-- -->. By default, `@lynx-js/css-extract-webpack-plugin` generates JS modules that use the ES modules syntax. There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.

**Signature:**

```typescript
esModule?: boolean | undefined;
```

## Example

You can enable a CommonJS syntax using:

```js
import {CssExtractWebpackPlugin} from "@lynx-js/css-extract-webpack-plugin";
export default {
  plugins: [new CssExtractWebpackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: CssExtractWebpackPlugin.loader,
            options: {
              esModule: false,
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
```



---
url: /api/rspeedy/rspeedy.cssextractrspackloaderoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md)

## CssExtractRspackLoaderOptions interface

The options of CSS extract loader.

**Signature:**

```typescript
export interface CssExtractRspackLoaderOptions 
```

## Properties

| Property                                                                    | Modifiers | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------- | --------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [esModule?](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.esmodule.md) |           | boolean \| undefined | _(Optional)_ The same as [https://github.com/webpack-contrib/mini-css-extract-plugin#esModule](https://github.com/webpack-contrib/mini-css-extract-plugin#esModule)<!-- -->. By default, <code>@lynx-js/css-extract-webpack-plugin</code> generates JS modules that use the ES modules syntax. There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking. |



---
url: /api/rspeedy/rspeedy.cssextractrspackpluginoptions.ignoreorder.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md) > [ignoreOrder](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.ignoreorder.md)

## CssExtractRspackPluginOptions.ignoreOrder property

**Signature:**

```typescript
ignoreOrder?: boolean | undefined;
```



---
url: /api/rspeedy/rspeedy.cssextractrspackpluginoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md)

## CssExtractRspackPluginOptions interface

The options for [CssExtractRspackPlugin](https://rspack.dev/plugins/rspack/css-extract-rspack-plugin)

**Signature:**

```typescript
export interface CssExtractRspackPluginOptions
```

## Properties

| Property                                                                          | Modifiers | Type                 | Description  |
| --------------------------------------------------------------------------------- | --------- | -------------------- | ------------ |
| [ignoreOrder?](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.ignoreorder.md) |           | boolean \| undefined | _(Optional)_ |
| [pathinfo?](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.pathinfo.md)       |           | boolean \| undefined | _(Optional)_ |



---
url: /api/rspeedy/rspeedy.cssextractrspackpluginoptions.pathinfo.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md) > [pathinfo](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.pathinfo.md)

## CssExtractRspackPluginOptions.pathinfo property

**Signature:**

```typescript
pathinfo?: boolean | undefined;
```



---
url: /api/rspeedy/rspeedy.cssloader.importloaders.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoader](/api/rspeedy/rspeedy.cssloader.md) > [importLoaders](/api/rspeedy/rspeedy.cssloader.importloaders.md)

## CssLoader.importLoaders property

The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@imported` resources and CSS modules imports.

**Signature:**

```typescript
importLoaders?: 0 | 1 | 2 | undefined;
```

## Remarks

The default value of `importLoaders` is:

- `1` when compiling CSS files

- `2` when compiling Sass or Less files

See [css-loader#import-loaders](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#importloaders) for details.



---
url: /api/rspeedy/rspeedy.cssloader.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoader](/api/rspeedy/rspeedy.cssloader.md)

## CssLoader interface

The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.

**Signature:**

```typescript
export interface CssLoader 
```

## Remarks

The default option is as follow:

```js
const defaultOptions = {
  modules: {
    auto: true,
    namedExport: false,
    exportLocalsConvention: 'camelCase',
    localIdentName: output.cssModules.localIdentName,
  },
  sourceMap: output.sourceMap,
  // importLoaders is `1` when compiling css files, and is `2` when compiling sass/less files
  importLoaders: 1 || 2,
};
```

## Properties

| Property                                                          | Modifiers | Type                                                                                 | Description                                                                                                                                                                                               |
| ----------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [importLoaders?](/api/rspeedy/rspeedy.cssloader.importloaders.md) |           | 0 \| 1 \| 2 \| undefined                                                             | _(Optional)_ The option <code>importLoaders</code> allows you to configure how many loaders before <code>css-loader</code> should be applied to <code>@imported</code> resources and CSS modules imports. |
| [modules?](/api/rspeedy/rspeedy.cssloader.modules.md)             |           | boolean \| [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) \| undefined | _(Optional)_ The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.                                            |



---
url: /api/rspeedy/rspeedy.cssloader.modules.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoader](/api/rspeedy/rspeedy.cssloader.md) > [modules](/api/rspeedy/rspeedy.cssloader.modules.md)

## CssLoader.modules property

The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.

**Signature:**

```typescript
modules?: boolean | CssLoaderModules | undefined;
```

## Example 1

Using `false` value to increase performance because we avoid parsing CSS Modules features, it will be useful for developers who use vanilla css or use other technologies.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    cssLoader: {
      modules: false,
    },
  },
})
```

## Example 2

Using `() => true` value to enable CSS Modules for all files.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    cssLoader: {
      modules: () => true,
    },
  },
})
```

## Example 3

Using object value to enable CSS Modules based-on [CssLoaderModules.auto](/api/rspeedy/rspeedy.cssloadermodules.auto.md) option and setup more configurations about CSS Modules.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    cssLoader: {
      modules: {
        namedExport: true,
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.cssloadermodules.auto.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [auto](/api/rspeedy/rspeedy.cssloadermodules.auto.md)

## CssLoaderModules.auto property

The `auto` option allows CSS modules to be automatically enabled based on their filenames.

**Signature:**

```typescript
auto?: boolean | RegExp | ((filename: string) => boolean) | undefined;
```

## Remarks

Given the various `auto` values, the behavior is described as follows:

- `true`<!-- -->: enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` RegExp.

- `false`<!-- -->: disable CSS modules.

- `RegExp`<!-- -->: enable CSS modules for all files matching the `auto.test(filename)` RegExp.

- `function`<!-- -->: enable CSS modules based on the filter function.

See [css-loader#auto](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#auto) for details.



---
url: /api/rspeedy/rspeedy.cssloadermodules.exportlocalsconvention.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [exportLocalsConvention](/api/rspeedy/rspeedy.cssloadermodules.exportlocalsconvention.md)

## CssLoaderModules.exportLocalsConvention property

The style of exported class names.

**Signature:**

```typescript
exportLocalsConvention?: CssModuleLocalsConvention | undefined;
```

## Remarks

Given the various `exportLocalsConvention` values, the behavior is described as follows:

- `'asIs'`<!-- -->: Class names will be exported as is.

- `'camelCase'`<!-- -->: Class names will be camelized, the original class name will not to be removed from the locals

- `'camelCaseOnly'`<!-- -->: Class names will be camelized, the original class name will be removed from the locals

- `'dashes'`<!-- -->: Only dashes in class names will be camelized

- `'dashesOnly'`<!-- -->: Dashes in class names will be camelized, the original class name will be removed from the locals

See [css-loader#exportLocalsConvention](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention) for details.



---
url: /api/rspeedy/rspeedy.cssloadermodules.localidentname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [localIdentName](/api/rspeedy/rspeedy.cssloadermodules.localidentname.md)

## CssLoaderModules.localIdentName property

Sets the format of the className generated by CSS Modules after compilation.

**Signature:**

```typescript
localIdentName?: string | undefined;
```

## Remarks

The default value is `'[local]-[hash:base64:6]'` which combines the original class name with a 6-character hash.

Available placeholders:

- `[local]`<!-- -->: Original class name

- `[hash]`<!-- -->: Hash of the class name

- `[path]`<!-- -->: File path

- `[name]`<!-- -->: File name

- `[ext]`<!-- -->: File extension

See [css-loader#localIdentName](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#localIdentName) for details.



---
url: /api/rspeedy/rspeedy.cssloadermodules.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md)

## CssLoaderModules interface

The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.

**Signature:**

```typescript
export interface CssLoaderModules 
```

## Properties

| Property                                                                                   | Modifiers | Type                                                                                        | Description                                                                                                        |
| ------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [auto?](/api/rspeedy/rspeedy.cssloadermodules.auto.md)                                     |           | boolean \| RegExp \| ((filename: string) => boolean) \| undefined                           | _(Optional)_ The <code>auto</code> option allows CSS modules to be automatically enabled based on their filenames. |
| [exportLocalsConvention?](/api/rspeedy/rspeedy.cssloadermodules.exportlocalsconvention.md) |           | [CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md) \| undefined | _(Optional)_ The style of exported class names.                                                                    |
| [localIdentName?](/api/rspeedy/rspeedy.cssloadermodules.localidentname.md)                 |           | string \| undefined                                                                         | _(Optional)_ Sets the format of the className generated by CSS Modules after compilation.                          |
| [namedExport?](/api/rspeedy/rspeedy.cssloadermodules.namedexport.md)                       |           | boolean \| undefined                                                                        | _(Optional)_ Enables/disables ES modules named export for locals.                                                  |



---
url: /api/rspeedy/rspeedy.cssloadermodules.namedexport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [namedExport](/api/rspeedy/rspeedy.cssloadermodules.namedexport.md)

## CssLoaderModules.namedExport property

Enables/disables ES modules named export for locals.

**Signature:**

```typescript
namedExport?: boolean | undefined;
```

## Example

- `style.css`

```css
.foo-baz {
  color: red;
}
.bar {
  color: blue;
}
.default {
  color: green;
}
```

- `index.js`

```js
import * as styles from "./styles.css";

// If using `exportLocalsConvention: "as-is"` (default value):
console.log(styles["foo-baz"], styles.bar);

// If using `exportLocalsConvention: "camel-case-only"`:
console.log(styles.fooBaz, styles.bar);

// For the `default` class name
console.log(styles["_default"]);
```



---
url: /api/rspeedy/rspeedy.cssmodulelocalsconvention.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md)

## CssModuleLocalsConvention type

The style of exported class names.

**Signature:**

```typescript
export type CssModuleLocalsConvention = 'asIs' | 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly';
```

## Remarks

Given the various `exportLocalsConvention` values, the behavior is described as follows:

- `'asIs'`<!-- -->: Class names will be exported as is.

- `'camelCase'`<!-- -->: Class names will be camelized, the original class name will not to be removed from the locals

- `'camelCaseOnly'`<!-- -->: Class names will be camelized, the original class name will be removed from the locals

- `'dashes'`<!-- -->: Only dashes in class names will be camelized

- `'dashesOnly'`<!-- -->: Dashes in class names will be camelized, the original class name will be removed from the locals

See [css-loader#exportLocalsConvention](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention) for details.



---
url: /api/rspeedy/rspeedy.cssmodules.auto.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [auto](/api/rspeedy/rspeedy.cssmodules.auto.md)

## CssModules.auto property

The `auto` option allows CSS modules to be automatically enabled based on their filenames.

**Signature:**

```typescript
auto?: boolean | RegExp | ((filename: string) => boolean) | undefined;
```

## Remarks

Given the various `auto` values, the behavior is described as follows:

- `true`<!-- -->: enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` RegExp.

- `false`<!-- -->: disable CSS modules.

- `RegExp`<!-- -->: enable CSS modules for all files matching the `auto.test(filename)` RegExp.

- `function`<!-- -->: enable CSS modules based on the filter function.

See [css-loader#auto](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#auto) for details.

## Example

Enable CSS module for `*.module.css` and `shared/*.css`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: (filename) => {
        return filename.includes('.module.') || filename.includes('shared/')
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.cssmodules.exportglobals.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [exportGlobals](/api/rspeedy/rspeedy.cssmodules.exportglobals.md)

## CssModules.exportGlobals property

Allows exporting names from global class names, so you can use them via import.

**Signature:**

```typescript
exportGlobals?: boolean | undefined;
```

## Remarks

See [css-loader#exportGlobals](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportglobals) for details.



---
url: /api/rspeedy/rspeedy.cssmodules.exportlocalsconvention.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [exportLocalsConvention](/api/rspeedy/rspeedy.cssmodules.exportlocalsconvention.md)

## CssModules.exportLocalsConvention property

The style of exported class names.

**Signature:**

```typescript
exportLocalsConvention?: CssModuleLocalsConvention | undefined;
```

## Remarks

Given the various `exportLocalsConvention` values, the behavior is described as follows:

- `'asIs'`<!-- -->: Class names will be exported as is.

- `'camelCase'`<!-- -->: Class names will be camelized, the original class name will not to be removed from the locals

- `'camelCaseOnly'`<!-- -->: Class names will be camelized, the original class name will be removed from the locals

- `'dashes'`<!-- -->: Only dashes in class names will be camelized

- `'dashesOnly'`<!-- -->: Dashes in class names will be camelized, the original class name will be removed from the locals

See [css-loader#exportLocalsConvention](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention) for details.



---
url: /api/rspeedy/rspeedy.cssmodules.localidentname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [localIdentName](/api/rspeedy/rspeedy.cssmodules.localidentname.md)

## CssModules.localIdentName property

Sets the format of the className generated by CSS Modules after compilation.

**Signature:**

```typescript
localIdentName?: string | undefined;
```

## Remarks

The default value is `'[local]-[hash:base64:6]'` which combines the original class name with a 6-character hash.

Available placeholders:

- `[local]`<!-- -->: Original class name

- `[hash]`<!-- -->: Hash of the class name

- `[path]`<!-- -->: File path

- `[name]`<!-- -->: File name

- `[ext]`<!-- -->: File extension

See [css-loader#localIdentName](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#localIdentName) for details.

## Example 1

Use only hash for shorter class names:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      localIdentName: '[hash:base64:8]',
    },
  },
})
```

## Example 2

Include file name for debugging:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      localIdentName: '[name]__[local]--[hash:base64:5]',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.cssmodules.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md)

## CssModules interface

The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.

**Signature:**

```typescript
export interface CssModules 
```

## Remarks

The CSS module is enabled for `*.module.css`<!-- -->, `*.module.scss` and `*.module.less`<!-- -->. Use [CssModules.auto](/api/rspeedy/rspeedy.cssmodules.auto.md) to customize the filtering behavior.

## Properties

| Property                                                                             | Modifiers | Type                                                                                        | Description                                                                                                        |
| ------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [auto?](/api/rspeedy/rspeedy.cssmodules.auto.md)                                     |           | boolean \| RegExp \| ((filename: string) => boolean) \| undefined                           | _(Optional)_ The <code>auto</code> option allows CSS modules to be automatically enabled based on their filenames. |
| [exportGlobals?](/api/rspeedy/rspeedy.cssmodules.exportglobals.md)                   |           | boolean \| undefined                                                                        | _(Optional)_ Allows exporting names from global class names, so you can use them via import.                       |
| [exportLocalsConvention?](/api/rspeedy/rspeedy.cssmodules.exportlocalsconvention.md) |           | [CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md) \| undefined | _(Optional)_ The style of exported class names.                                                                    |
| [localIdentName?](/api/rspeedy/rspeedy.cssmodules.localidentname.md)                 |           | string \| undefined                                                                         | _(Optional)_ Sets the format of the className generated by CSS Modules after compilation.                          |



---
url: /api/rspeedy/rspeedy.decorators.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Decorators](/api/rspeedy/rspeedy.decorators.md)

## Decorators interface

Used to configure the decorators syntax.

**Signature:**

```typescript
export interface Decorators 
```

## Remarks

See [Decorators.version](/api/rspeedy/rspeedy.decorators.version.md) for more information.

## Properties

| Property                                               | Modifiers | Type                  | Description                                                   |
| ------------------------------------------------------ | --------- | --------------------- | ------------------------------------------------------------- |
| [version?](/api/rspeedy/rspeedy.decorators.version.md) |           | 'legacy' \| '2022-03' | _(Optional)_ Specify the decorator syntax version to be used. |



---
url: /api/rspeedy/rspeedy.decorators.version.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Decorators](/api/rspeedy/rspeedy.decorators.md) > [version](/api/rspeedy/rspeedy.decorators.version.md)

## Decorators.version property

Specify the decorator syntax version to be used.

**Signature:**

```typescript
version?: 'legacy' | '2022-03';
```

## Remarks

If you want to know the differences between different decorators versions, you can refer to: [How does this proposal compare to other versions of decorators?](https://github.com/tc39/proposal-decorators?tab=readme-ov-file#how-does-this-proposal-compare-to-other-versions-of-decorators)

## Example 1

`'2022-03'` corresponds to the Stage 3 decorator proposal, equivalent to the decorator syntax supported by TypeScript 5.0 by default.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    decorators: { version: '2022-03' },
  },
})
```

## Example 2

`'legacy'` corresponds to TypeScript's `experimentalDecorators: true`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    decorators: { version: 'legacy' },
  },
})
```



---
url: /api/rspeedy/rspeedy.defineconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: Config): Config;
```

## Parameters

| Parameter | Type                                     | Description            |
| --------- | ---------------------------------------- | ---------------------- |
| config    | [Config](/api/rspeedy/rspeedy.config.md) | The config of Rspeedy. |

**Returns:**

[Config](/api/rspeedy/rspeedy.config.md)

- The identical config as the input config.

## Example

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  // autocompletion works here!
})
```



---
url: /api/rspeedy/rspeedy.defineconfig_1.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig_1.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: (params: ConfigParams) => Config): (params: ConfigParams) => Config;
```

## Parameters

| Parameter | Type                                                                                                               | Description                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| config    | (params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => [Config](/api/rspeedy/rspeedy.config.md) | The function that returns a config of Rspeedy. |

**Returns:**

(params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => [Config](/api/rspeedy/rspeedy.config.md)

- The identical function as the input.

## Example 1

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig(() => {
  return {
    // autocompletion works here!
  }
})
```

## Example 2

Use `defineConfig` with parameters in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig(({ env }) => {
  const isTest = env === 'test'
  return {
    output: {
      minify: isTest ? false : true,
    },
  }
})
```



---
url: /api/rspeedy/rspeedy.defineconfig_2.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig_2.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: Promise<Config>): Promise<Config>;
```

## Parameters

| Parameter | Type                                                       | Description                                       |
| --------- | ---------------------------------------------------------- | ------------------------------------------------- |
| config    | Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->> | The promise that resolves to a config of Rspeedy. |

**Returns:**

Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->>

- The identical promise as the input.

## Example

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig(
  import('@lynx-js/react-rsbuild-plugin').then(({ pluginReactLynx }) => ({
    plugins: [pluginReactLynx()],
  })),
);
```



---
url: /api/rspeedy/rspeedy.defineconfig_3.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig_3.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: (params: ConfigParams) => Promise<Config>): (params: ConfigParams) => Promise<Config>;
```

## Parameters

| Parameter | Type                                                                                                                                 | Description                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| config    | (params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->> | The function that returns a promise that resolves to a config of Rspeedy. |

**Returns:**

(params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->>

- The identical function as the input.

## Example 1

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig(async () => {
  const foo = await bar()
  return {
    // autocompletion works here!
  }
})
```

## Example 2

Use `defineConfig` with parameters in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig(async ({ env }) => {
  const foo = await bar()
  const isTest = env === 'test'
  return {
    output: {
      minify: isTest ? false : true,
    },
  }
})
```



---
url: /api/rspeedy/rspeedy.dev.assetprefix.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md)

## Dev.assetPrefix property

The [Dev.assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md) is used to set the URL prefix for static assets during development.

**Signature:**

```typescript
assetPrefix?: string | boolean | undefined;
```

## Remarks

The functionality of [Dev.assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md) is basically the same as the [output.publicPath](https://www.rspack.dev/config/output#outputpublicpath) config in Rspack. With the following differences:

- `dev.assetPrefix` only takes effect during development.

- `dev.assetPrefix` automatically appends a trailing `/` by default.

- The value of `dev.assetPrefix` is written to the `process.env.ASSET_PREFIX` environment variable.

## Example 1

If `dev.assetPrefix` is set to true, the URL prefix will be `http://<host>:<port>/`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    assetPrefix: true,
  },
})
```

## Example 2

If `dev.assetPrefix` is set to a string, the value will be used as a prefix and automatically appended to the static resource URL.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    assetPrefix: 'https://example.com/assets/',
  },
})
```

## Example 3

The port number that Rspeedy server listens on may change. For example, if the port is in use, Rspeedy will automatically increment the port number until it finds an available port.

To avoid `dev.assetPrefix` becoming invalid due to port changes, you can use one of the following methods:

- Enable `server.strictPort`<!-- -->.

- Use the `<port>` placeholder to refer to the current port number. Rspeedy will replace the placeholder with the actual port number it is listening on.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    assetPrefix: 'https://example.com:<port>/assets/',
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.client.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [client](/api/rspeedy/rspeedy.dev.client.md)

## Dev.client property

Configuration of the development client.

**Signature:**

```typescript
client?: Client | undefined;
```



---
url: /api/rspeedy/rspeedy.dev.hmr.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [hmr](/api/rspeedy/rspeedy.dev.hmr.md)

## Dev.hmr property

Whether to enable Hot Module Replacement (HMR).

**Signature:**

```typescript
hmr?: boolean | undefined;
```

## Remarks

Defaults to `true`<!-- -->.

By default, Rspeedy uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to [Dev.liveReload](/api/rspeedy/rspeedy.dev.livereload.md)<!-- -->.

To completely disable both HMR and live reload, set both `dev.hmr` and `dev.liveReload` to `false`<!-- -->. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when file changes.

## Example 1

Disable HMR:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    hmr: false,
  },
})
```

## Example 2

Disable both HMR and live reload:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    hmr: false,
    liveReload: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.livereload.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [liveReload](/api/rspeedy/rspeedy.dev.livereload.md)

## Dev.liveReload property

Whether to enable live reload functionality.

Defaults to `true`<!-- -->.

Live reload is used as a fallback when [Dev.hmr](/api/rspeedy/rspeedy.dev.hmr.md) is disabled or cannot be used in certain scenarios. When enabled, the page will automatically refresh when source files are changed.

To completely disable both HMR and live reload, set both `dev.hmr` and `dev.liveReload` to `false`<!-- -->. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when file changes.

**Signature:**

```typescript
liveReload?: boolean | undefined;
```

## Example 1

Disable live reload:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    liveReload: false,
  },
})
```

## Example 2

Disable both HMR and live reload:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    hmr: false,
    liveReload: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md)

## Dev interface

The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc.

**Signature:**

```typescript
export interface Dev 
```

## Properties

| Property                                                | Modifiers | Type                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------- | --------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [assetPrefix?](/api/rspeedy/rspeedy.dev.assetprefix.md) |           | string \| boolean \| undefined                           | _(Optional)_ The [Dev.assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md) is used to set the URL prefix for static assets during development.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [client?](/api/rspeedy/rspeedy.dev.client.md)           |           | [Client](/api/rspeedy/rspeedy.devclient.md) \| undefined | _(Optional)_ Configuration of the development client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [hmr?](/api/rspeedy/rspeedy.dev.hmr.md)                 |           | boolean \| undefined                                     | _(Optional)_ Whether to enable Hot Module Replacement (HMR).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [liveReload?](/api/rspeedy/rspeedy.dev.livereload.md)   |           | boolean \| undefined                                     | <p>_(Optional)_ Whether to enable live reload functionality.</p><p>Defaults to <code>true</code>.</p><p>Live reload is used as a fallback when [Dev.hmr](/api/rspeedy/rspeedy.dev.hmr.md) is disabled or cannot be used in certain scenarios. When enabled, the page will automatically refresh when source files are changed.</p><p>To completely disable both HMR and live reload, set both <code>dev.hmr</code> and <code>dev.liveReload</code> to <code>false</code>. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when file changes.</p> |
| [progressBar?](/api/rspeedy/rspeedy.dev.progressbar.md) |           | boolean \| \{ id?: string; } \| undefined                | <p>_(Optional)_ Whether to display progress bar during compilation.</p><p>Defaults to <code>true</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [watchFiles?](/api/rspeedy/rspeedy.dev.watchfiles.md)   |           | WatchFiles \| WatchFiles\[] \| undefined                 | _(Optional)_ Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [writeToDisk?](/api/rspeedy/rspeedy.dev.writetodisk.md) |           | boolean \| ((filename: string) => boolean) \| undefined  | _(Optional)_ Used to control whether the build artifacts of the development environment are written to the disk.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |



---
url: /api/rspeedy/rspeedy.dev.progressbar.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [progressBar](/api/rspeedy/rspeedy.dev.progressbar.md)

## Dev.progressBar property

Whether to display progress bar during compilation.

Defaults to `true`<!-- -->.

**Signature:**

```typescript
progressBar?: boolean | {
        id?: string;
    } | undefined;
```

## Example 1

Disable the progress bar.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    progressBar: false,
  },
})
```

## Example 2

Modify the progress bar `id`

To modify the text displayed on the left side of the progress bar, set the `id` option:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    progressBar: {
      id: 'Some Text'
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.watchfiles.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [watchFiles](/api/rspeedy/rspeedy.dev.watchfiles.md)

## Dev.watchFiles property

Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.

**Signature:**

```typescript
watchFiles?: WatchFiles | WatchFiles[] | undefined;
```

## Example 1

- Specify the files and directories watched for changes.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    watchFiles: {
      paths: ['src/**', 'public/**'],
    },
  },
})
```

## Example 2

- Use [chokidar](https://github.com/paulmillr/chokidar#api) options for watching.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    watchFiles: {
      paths: ['src/**', 'public/**'],
      options: { usePolling: false },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.writetodisk.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [writeToDisk](/api/rspeedy/rspeedy.dev.writetodisk.md)

## Dev.writeToDisk property

Used to control whether the build artifacts of the development environment are written to the disk.

**Signature:**

```typescript
writeToDisk?: boolean | ((filename: string) => boolean) | undefined;
```

## Remarks

This is bypassed to [\`webpack-dev-middleware\`](https://github.com/webpack/webpack-dev-middleware?tab=readme-ov-file#writetodisk)<!-- -->.

Setting `writeToDisk: true` won't change the behavior of the `webpack-dev-middleware`<!-- -->, and bundle files accessed through the browser will still be served from memory.

This option also accepts a `Function` value, which can be used to filter which files are written to disk.

The function follows the same premise as `Array#filter` in which a return value of `false` will not write the file, and a return value of `true` will write the file to disk.

## Example

```js
// lynx.config.ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    writeToDisk: (filePath) => /superman\.css$/.test(filePath),
  },
})
```



---
url: /api/rspeedy/rspeedy.devclient.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DevClient](/api/rspeedy/rspeedy.devclient.md)

## DevClient interface

Configuration of the development client.

**Signature:**

```typescript
export interface Client 
```

## Properties

| Property                                                                    | Modifiers | Type                | Description                         |
| --------------------------------------------------------------------------- | --------- | ------------------- | ----------------------------------- |
| [websocketTransport?](/api/rspeedy/rspeedy.devclient.websockettransport.md) |           | string \| undefined | _(Optional)_ The path to websocket. |



---
url: /api/rspeedy/rspeedy.devclient.websockettransport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DevClient](/api/rspeedy/rspeedy.devclient.md) > [websocketTransport](/api/rspeedy/rspeedy.devclient.websockettransport.md)

## DevClient.websocketTransport property

The path to websocket.

**Signature:**

```typescript
websocketTransport?: string | undefined;
```

## Remarks

Defaults to `require.resolve('@lynx-js/websocket')`



---
url: /api/rspeedy/rspeedy.distpath.css.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md) > [css](/api/rspeedy/rspeedy.distpath.css.md)

## DistPath.css property

The output directory of CSS style files.

**Signature:**

```typescript
css?: string | undefined;
```

## Remarks

Default value:

- The same as [DistPath.intermediate](/api/rspeedy/rspeedy.distpath.intermediate.md)



---
url: /api/rspeedy/rspeedy.distpath.cssasync.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md) > [cssAsync](/api/rspeedy/rspeedy.distpath.cssasync.md)

## DistPath.cssAsync property

The output directory of async JavaScript files.

**Signature:**

```typescript
cssAsync?: string | undefined;
```

## Remarks

Default value:

- The `async` subdirectory of [DistPath.css](/api/rspeedy/rspeedy.distpath.css.md)<!-- -->.



---
url: /api/rspeedy/rspeedy.distpath.intermediate.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md) > [intermediate](/api/rspeedy/rspeedy.distpath.intermediate.md)

## DistPath.intermediate property

> Warning: This API is now obsolete.
>
> This option is never read and will be removed in the future version.

The output directory of the intermediate files.

**Signature:**

```typescript
intermediate?: string | undefined;
```

## Remarks

Default value:

- `'.rspeedy'`



---
url: /api/rspeedy/rspeedy.distpath.js.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md) > [js](/api/rspeedy/rspeedy.distpath.js.md)

## DistPath.js property

The output directory of JavaScript files.

**Signature:**

```typescript
js?: string | undefined;
```

## Remarks

Default value:

- `'static/js'`



---
url: /api/rspeedy/rspeedy.distpath.jsasync.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md) > [jsAsync](/api/rspeedy/rspeedy.distpath.jsasync.md)

## DistPath.jsAsync property

The output directory of async JavaScript files.

**Signature:**

```typescript
jsAsync?: string | undefined;
```

## Remarks

Default value:

- The `async` subdirectory of [DistPath.js](/api/rspeedy/rspeedy.distpath.js.md)<!-- -->.



---
url: /api/rspeedy/rspeedy.distpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md)

## DistPath interface

Set the directory of the dist files.

**Signature:**

```typescript
export interface DistPath extends DistPathConfig 
```

**Extends:** DistPathConfig

## Remarks

More options can be found at [Rsbuild - distPath](https://rsbuild.dev/config/output/dist-path)<!-- -->.

## Properties

| Property                                                       | Modifiers | Type                | Description                                                  |
| -------------------------------------------------------------- | --------- | ------------------- | ------------------------------------------------------------ |
| [intermediate?](/api/rspeedy/rspeedy.distpath.intermediate.md) |           | string \| undefined | _(Optional)_ The output directory of the intermediate files. |



---
url: /api/rspeedy/rspeedy.distpath.root.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md) > [root](/api/rspeedy/rspeedy.distpath.root.md)

## DistPath.root property

The root directory of all output files.

**Signature:**

```typescript
root?: string | undefined;
```

## Remarks

Default value:

- `'dist'`



---
url: /api/rspeedy/rspeedy.entry.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Entry](/api/rspeedy/rspeedy.entry.md)

## Entry type

The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module.

**Signature:**

```typescript
export type Entry = string | string[] | Record<string, string | string[] | EntryDescription>;
```

**References:** [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)

## Remarks

If no value is provided, the default value `'./src/index.js'` will be used.

## Example 1

- Use a single entry:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: './src/pages/main/index.js',
  }
})
```

## Example 2

- Use a single entry with multiple entry modules:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: ['./src/prefetch.js', './src/pages/main/index.js'],
  }
})
```

## Example 3

- Use multiple entries(with multiple entry modules):

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: ['./src/pages/bar/index.js', './src/post.js'], // multiple entry modules is allowed
    }
  }
})
```

## Example 4

- Use multiple entries with [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: {
        import: ['./src/prefetch.js', './src/pages/bar'],
      }
    }
  }
})
```



---
url: /api/rspeedy/rspeedy.entrydescription.import.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md) > [import](/api/rspeedy/rspeedy.entrydescription.import.md)

## EntryDescription.import property

The path to the entry module(s).

**Signature:**

```typescript
import?: string | string[] | undefined;
```

## Remarks

If no value is provided, the default value `src/index.js` will be used.



---
url: /api/rspeedy/rspeedy.entrydescription.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)

## EntryDescription interface

The `EntryDescription` describes a entry. It is useful when the project has multiple entries with different configuration.

**Signature:**

```typescript
export interface EntryDescription 
```

## Remarks

It is similar with the [Entry Description Object](https://www.rspack.dev/config/entry#entry-description-object) of Rspack. But only a few properties that Lynx supports is allowed.

## Properties

| Property                                                           | Modifiers | Type                             | Description                                                                                                                                                                                                              |
| ------------------------------------------------------------------ | --------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [import?](/api/rspeedy/rspeedy.entrydescription.import.md)         |           | string \| string\[] \| undefined | _(Optional)_ The path to the entry module(s).                                                                                                                                                                            |
| [publicPath?](/api/rspeedy/rspeedy.entrydescription.publicpath.md) |           | string \| undefined              | _(Optional)_ This is an important option when using on-demand-loading or loading external resources like images, files, etc. If an incorrect value is specified you'll receive 404 errors while loading these resources. |



---
url: /api/rspeedy/rspeedy.entrydescription.publicpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md) > [publicPath](/api/rspeedy/rspeedy.entrydescription.publicpath.md)

## EntryDescription.publicPath property

This is an important option when using on-demand-loading or loading external resources like images, files, etc. If an incorrect value is specified you'll receive 404 errors while loading these resources.

**Signature:**

```typescript
publicPath?: string | undefined;
```



---
url: /api/rspeedy/rspeedy.exposedapi.config.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [config](/api/rspeedy/rspeedy.exposedapi.config.md)

## ExposedAPI.config property

The user config.

**Signature:**

```typescript
config: Config;
```



---
url: /api/rspeedy/rspeedy.exposedapi.debug.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [debug](/api/rspeedy/rspeedy.exposedapi.debug.md)

## ExposedAPI.debug property

Print debug logs.

**Signature:**

```typescript
debug: (message: string | (() => string)) => void;
```



---
url: /api/rspeedy/rspeedy.exposedapi.exit.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [exit](/api/rspeedy/rspeedy.exposedapi.exit.md)

## ExposedAPI.exit property

Exit the process.

**Signature:**

```typescript
exit: (code?: number) => Promise<void> | void;
```



---
url: /api/rspeedy/rspeedy.exposedapi.logger.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [logger](/api/rspeedy/rspeedy.exposedapi.logger.md)

## ExposedAPI.logger property

Get the Rspeedy logger.

**Signature:**

```typescript
logger: typeof logger;
```



---
url: /api/rspeedy/rspeedy.exposedapi.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md)

## ExposedAPI interface

The exposed API of Rspeedy. Can be used in Rsbuild plugin with [api.useExposed](https://rsbuild.dev/plugins/dev/core#apiuseexposed)<!-- -->.

**Signature:**

```typescript
export interface ExposedAPI 
```

## Example

```ts
import type { ExposedAPI } from '@lynx-js/rspeedy'
const RsbuildPlugin = {
  name: 'my-rsbuild-plugin',
  pre: ['lynx:rsbuild:plugin-api'],
  setup(api) {
    const rspeedyAPI = api.useExposed<ExposedAPI>(Symbol.for('rspeedy.api'))
  },
}
```

## Properties

| Property                                              | Modifiers | Type                                        | Description             |
| ----------------------------------------------------- | --------- | ------------------------------------------- | ----------------------- |
| [config](/api/rspeedy/rspeedy.exposedapi.config.md)   |           | [Config](/api/rspeedy/rspeedy.config.md)    | The user config.        |
| [debug](/api/rspeedy/rspeedy.exposedapi.debug.md)     |           | (message: string \| (() => string)) => void | Print debug logs.       |
| [exit](/api/rspeedy/rspeedy.exposedapi.exit.md)       |           | (code?: number) => Promise\<void> \| void   | Exit the process.       |
| [logger](/api/rspeedy/rspeedy.exposedapi.logger.md)   |           | typeof logger                               | Get the Rspeedy logger. |
| [version](/api/rspeedy/rspeedy.exposedapi.version.md) |           | string                                      | The version of Rspeedy. |



---
url: /api/rspeedy/rspeedy.exposedapi.version.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [version](/api/rspeedy/rspeedy.exposedapi.version.md)

## ExposedAPI.version property

The version of Rspeedy.

**Signature:**

```typescript
version: string;
```



---
url: /api/rspeedy/rspeedy.filename.assets.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [assets](/api/rspeedy/rspeedy.filename.assets.md)

## Filename.assets property

The name of other assets, except for above (image, svg, font, html, wasm...)

**Signature:**

```typescript
assets?: Rspack.AssetModuleFilename;
```

## Remarks

Default values:

- `'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.bundle.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [bundle](/api/rspeedy/rspeedy.filename.bundle.md)

## Filename.bundle property

The name of the bundle files.

**Signature:**

```typescript
bundle?: string | undefined;
```

## Remarks

Default values:

- `'[name].[platform].bundle'`

The following placeholder is supported:

- `[name]`<!-- -->: the name of the entry. - `[contenthash]`<!-- -->: the contenthash of the bundle. - `[platform]`<!-- -->: the environment name of the bundle.

## Example 1

- Using content hash in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      bundle: '[name].[contenthash].bundle',
    },
  },
})
```

## Example 2

- Using content hash with length in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      bundle: '[name].[contenthash:8].bundle',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.css.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [css](/api/rspeedy/rspeedy.filename.css.md)

## Filename.css property

The name of the CSS files.

**Signature:**

```typescript
css?: Rspack.CssFilename | undefined;
```

## Remarks

Default values:

- `'[name].css'`

## Example

- Using a function to dynamically set the filename based on the file information:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      css: (pathData, assetInfo) => {
        console.log(pathData); // You can check the contents of pathData here

        if (pathData.chunk?.name === 'index') {
          return isProd ? '[name].[contenthash:8].css' : '[name].css';
        }
        return '/some-path/[name].css';
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.font.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [font](/api/rspeedy/rspeedy.filename.font.md)

## Filename.font property

The name of the font files.

**Signature:**

```typescript
font?: Rspack.AssetModuleFilename | undefined;
```

## Remarks

Default values:

- `'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.image.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [image](/api/rspeedy/rspeedy.filename.image.md)

## Filename.image property

The name of non-SVG images.

**Signature:**

```typescript
image?: Rspack.AssetModuleFilename | undefined;
```

## Remarks

Default values:

- `'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.js.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [js](/api/rspeedy/rspeedy.filename.js.md)

## Filename.js property

The name of the JavaScript files.

**Signature:**

```typescript
js?: Rspack.Filename | undefined;
```

## Remarks

Default values:

- Development: `'[name].js'` - Production: `'[name].[contenthash:8].js'`

## Example

- Using a function to dynamically set the filename based on the file information:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      js: (pathData, assetInfo) => {
        console.log(pathData); // You can check the contents of pathData here

        if (pathData.chunk?.name === 'index') {
          return isProd ? '[name].[contenthash:8].js' : '[name].js';
        }
        return '/some-path/[name].js';
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md)

## Filename interface

The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.

**Signature:**

```typescript
export interface Filename 
```

## Remarks

If a string is provided, it will be used as [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md)<!-- -->.

## Properties

| Property                                               | Modifiers | Type                                    | Description                                                                               |
| ------------------------------------------------------ | --------- | --------------------------------------- | ----------------------------------------------------------------------------------------- |
| [assets?](/api/rspeedy/rspeedy.filename.assets.md)     |           | Rspack.AssetModuleFilename              | _(Optional)_ The name of other assets, except for above (image, svg, font, html, wasm...) |
| [bundle?](/api/rspeedy/rspeedy.filename.bundle.md)     |           | string \| undefined                     | _(Optional)_ The name of the bundle files.                                                |
| [css?](/api/rspeedy/rspeedy.filename.css.md)           |           | Rspack.CssFilename \| undefined         | _(Optional)_ The name of the CSS files.                                                   |
| [font?](/api/rspeedy/rspeedy.filename.font.md)         |           | Rspack.AssetModuleFilename \| undefined | _(Optional)_ The name of the font files.                                                  |
| [image?](/api/rspeedy/rspeedy.filename.image.md)       |           | Rspack.AssetModuleFilename \| undefined | _(Optional)_ The name of non-SVG images.                                                  |
| [js?](/api/rspeedy/rspeedy.filename.js.md)             |           | Rspack.Filename \| undefined            | _(Optional)_ The name of the JavaScript files.                                            |
| [media?](/api/rspeedy/rspeedy.filename.media.md)       |           | Rspack.AssetModuleFilename \| undefined | _(Optional)_ The name of media assets, such as video.                                     |
| [svg?](/api/rspeedy/rspeedy.filename.svg.md)           |           | Rspack.AssetModuleFilename \| undefined | _(Optional)_ The name of the SVG images.                                                  |
| [template?](/api/rspeedy/rspeedy.filename.template.md) |           | string \| undefined                     | _(Optional)_ The name of the template files.                                              |
| [wasm?](/api/rspeedy/rspeedy.filename.wasm.md)         |           | Rspack.WebassemblyModuleFilename        | _(Optional)_ The name of WebAssembly files.                                               |



---
url: /api/rspeedy/rspeedy.filename.media.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [media](/api/rspeedy/rspeedy.filename.media.md)

## Filename.media property

The name of media assets, such as video.

**Signature:**

```typescript
media?: Rspack.AssetModuleFilename | undefined;
```

## Remarks

Default values:

- `'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.svg.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [svg](/api/rspeedy/rspeedy.filename.svg.md)

## Filename.svg property

The name of the SVG images.

**Signature:**

```typescript
svg?: Rspack.AssetModuleFilename | undefined;
```

## Remarks

Default values:

- `'[name].[contenthash:8].svg'`



---
url: /api/rspeedy/rspeedy.filename.template.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [template](/api/rspeedy/rspeedy.filename.template.md)

## Filename.template property

> Warning: This API is now obsolete.
>
> Use [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md) instead.

The name of the template files.

**Signature:**

```typescript
template?: string | undefined;
```

## Remarks

Default values:

- `'[name].lynx.bundle'`

The following placeholder is supported:

- `[name]`<!-- -->: the name of the entry. - `[contenthash]`<!-- -->: the contenthash of the template.

## Example 1

- Using content hash in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      template: '[name].[contenthash].bundle',
    },
  },
})
```

## Example 2

- Using content hash with length in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      template: '[name].[contenthash:8].bundle',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.wasm.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [wasm](/api/rspeedy/rspeedy.filename.wasm.md)

## Filename.wasm property

The name of WebAssembly files.

**Signature:**

```typescript
wasm?: Rspack.WebassemblyModuleFilename;
```

## Remarks

Default values:

- `'[hash].module.wasm'`



---
url: /api/rspeedy/rspeedy.loadconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [loadConfig](/api/rspeedy/rspeedy.loadconfig.md)

## loadConfig() function

Load the build config by the config path.

**Signature:**

```typescript
export declare function loadConfig(loadConfigOptions: LoadConfigOptions): Promise<LoadConfigResult>;
```

## Parameters

| Parameter         | Type                                                           | Description                                    |
| ----------------- | -------------------------------------------------------------- | ---------------------------------------------- |
| loadConfigOptions | [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md) | the options of <code>loadConfig</code> method. |

**Returns:**

Promise\<[LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md)<!-- -->>

Build config.

## Example

```ts
import { loadConfig } from '@lynx-js/rspeedy'

void async function () {
  const config = await loadConfig({ configPath: './lynx.config.js' })
  console.log(config);
}()
```



---
url: /api/rspeedy/rspeedy.loadconfigoptions.configpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md) > [configPath](/api/rspeedy/rspeedy.loadconfigoptions.configpath.md)

## LoadConfigOptions.configPath property

**Signature:**

```typescript
configPath?: string | undefined;
```



---
url: /api/rspeedy/rspeedy.loadconfigoptions.cwd.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md) > [cwd](/api/rspeedy/rspeedy.loadconfigoptions.cwd.md)

## LoadConfigOptions.cwd property

**Signature:**

```typescript
cwd?: string | undefined;
```



---
url: /api/rspeedy/rspeedy.loadconfigoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md)

## LoadConfigOptions interface

The options of loadConfig.

**Signature:**

```typescript
export interface LoadConfigOptions 
```

## Properties

| Property                                                            | Modifiers | Type                | Description  |
| ------------------------------------------------------------------- | --------- | ------------------- | ------------ |
| [configPath?](/api/rspeedy/rspeedy.loadconfigoptions.configpath.md) |           | string \| undefined | _(Optional)_ |
| [cwd?](/api/rspeedy/rspeedy.loadconfigoptions.cwd.md)               |           | string \| undefined | _(Optional)_ |



---
url: /api/rspeedy/rspeedy.loadconfigresult.configpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md) > [configPath](/api/rspeedy/rspeedy.loadconfigresult.configpath.md)

## LoadConfigResult.configPath property

The configuration path that has been loaded.

**Signature:**

```typescript
configPath: string;
```



---
url: /api/rspeedy/rspeedy.loadconfigresult.content.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md) > [content](/api/rspeedy/rspeedy.loadconfigresult.content.md)

## LoadConfigResult.content property

The configuration object that exported from the configuration file.

**Signature:**

```typescript
content: Config;
```

## Remarks

The returned object has already been validated.



---
url: /api/rspeedy/rspeedy.loadconfigresult.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md)

## LoadConfigResult interface

The result of [loadConfig()](/api/rspeedy/rspeedy.loadconfig.md)<!-- -->.

**Signature:**

```typescript
export interface LoadConfigResult 
```

## Properties

| Property                                                          | Modifiers | Type                                     | Description                                                         |
| ----------------------------------------------------------------- | --------- | ---------------------------------------- | ------------------------------------------------------------------- |
| [configPath](/api/rspeedy/rspeedy.loadconfigresult.configpath.md) |           | string                                   | The configuration path that has been loaded.                        |
| [content](/api/rspeedy/rspeedy.loadconfigresult.content.md)       |           | [Config](/api/rspeedy/rspeedy.config.md) | The configuration object that exported from the configuration file. |



---
url: /api/rspeedy/rspeedy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md)

## rspeedy package

The document contains all the configurations of the `@lynx-js/rspeedy` package.

## Example

Use `lynx.config.ts` with [defineConfig()](/api/rspeedy/rspeedy.defineconfig.md) to get better TypeScript intellisense.

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  entry: './src/index.tsx',
})
```

## Functions

| Function                                                                                                           | Description                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [createRspeedy(\{ cwd, rspeedyConfig, loadEnv, environment, callerName, })](/api/rspeedy/rspeedy.createrspeedy.md) | The <code>createRspeedy</code> method can let you create a Rspeedy instance and you can customize the build or development process in Node.js Runtime. |
| [defineConfig(config)](/api/rspeedy/rspeedy.defineconfig.md)                                                       | The <code>defineConfig</code> method is a helper function used to get TypeScript intellisense.                                                         |
| [defineConfig(config)](/api/rspeedy/rspeedy.defineconfig_1.md)                                                     | The <code>defineConfig</code> method is a helper function used to get TypeScript intellisense.                                                         |
| [defineConfig(config)](/api/rspeedy/rspeedy.defineconfig_2.md)                                                     | The <code>defineConfig</code> method is a helper function used to get TypeScript intellisense.                                                         |
| [defineConfig(config)](/api/rspeedy/rspeedy.defineconfig_3.md)                                                     | The <code>defineConfig</code> method is a helper function used to get TypeScript intellisense.                                                         |
| [loadConfig(loadConfigOptions)](/api/rspeedy/rspeedy.loadconfig.md)                                                | Load the build config by the config path.                                                                                                              |
| [mergeRspeedyConfig(configs)](/api/rspeedy/rspeedy.mergerspeedyconfig.md)                                          | Merge multiple Rspeedy configuration objects.                                                                                                          |

## Interfaces

| Interface                                                                              | Description                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [BuildCache](/api/rspeedy/rspeedy.buildcache.md)                                       | <p>**_(BETA)_** Enable or configure persistent build cache.</p><p>This feature is experimental and may be changed in the future.</p>                                                                                                                                                      |
| [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md)                                       | [Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.                                                                                                                                                               |
| [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md)                           | [Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.                                                                                                                                                               |
| [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md)                           | [Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.                                                                                                                                                               |
| [Config](/api/rspeedy/rspeedy.config.md)                                               | The <code>Config</code> is the configuration that <code>rspeedy</code> uses.                                                                                                                                                                                                              |
| [ConfigParams](/api/rspeedy/rspeedy.configparams.md)                                   | Parameters for the function exported from <code>lynx.config.js</code>.                                                                                                                                                                                                                    |
| [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md)                   | The options of <code>createRspeedy</code> method.                                                                                                                                                                                                                                         |
| [CssExtract](/api/rspeedy/rspeedy.cssextract.md)                                       | The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin)                                                                                                                    |
| [CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md) | The options of CSS extract loader.                                                                                                                                                                                                                                                        |
| [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md) | The options for [CssExtractRspackPlugin](https://rspack.dev/plugins/rspack/css-extract-rspack-plugin)                                                                                                                                                                                     |
| [CssLoader](/api/rspeedy/rspeedy.cssloader.md)                                         | The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.                                                                                                                                           |
| [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md)                           | The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.                                                                                                                                         |
| [CssModules](/api/rspeedy/rspeedy.cssmodules.md)                                       | The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.                                                                                                                                                                  |
| [Decorators](/api/rspeedy/rspeedy.decorators.md)                                       | Used to configure the decorators syntax.                                                                                                                                                                                                                                                  |
| [Dev](/api/rspeedy/rspeedy.dev.md)                                                     | The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc.                                                                                                                                                   |
| [DevClient](/api/rspeedy/rspeedy.devclient.md)                                         | Configuration of the development client.                                                                                                                                                                                                                                                  |
| [DistPath](/api/rspeedy/rspeedy.distpath.md)                                           | Set the directory of the dist files.                                                                                                                                                                                                                                                      |
| [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)                           | The <code>EntryDescription</code> describes a entry. It is useful when the project has multiple entries with different configuration.                                                                                                                                                     |
| [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md)                                       | The exposed API of Rspeedy. Can be used in Rsbuild plugin with [api.useExposed](https://rsbuild.dev/plugins/dev/core#apiuseexposed)<!-- -->.                                                                                                                                              |
| [Filename](/api/rspeedy/rspeedy.filename.md)                                           | The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.                                                                                                 |
| [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md)                         | The options of loadConfig.                                                                                                                                                                                                                                                                |
| [LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md)                           | The result of [loadConfig()](/api/rspeedy/rspeedy.loadconfig.md)<!-- -->.                                                                                                                                                                                                                 |
| [Minify](/api/rspeedy/rspeedy.minify.md)                                               | The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.                                                                                                                                   |
| [Output](/api/rspeedy/rspeedy.output.md)                                               | The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.                                                                                                                                                                    |
| [Performance](/api/rspeedy/rspeedy.performance.md)                                     | The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.                                                                                                                                                                 |
| [Resolve](/api/rspeedy/rspeedy.resolve.md)                                             | The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.                                                                                                                                                                               |
| [Server](/api/rspeedy/rspeedy.server.md)                                               | The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.                                                                                                                                                                                                   |
| [Source](/api/rspeedy/rspeedy.source.md)                                               | The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.                                                                                                                                                                                                 |
| [SourceMap](/api/rspeedy/rspeedy.sourcemap.md)                                         | The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.                                                                                                                                                                         |
| [Tools](/api/rspeedy/rspeedy.tools.md)                                                 | The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.                                                                                                                                                                                        |
| [TransformImport](/api/rspeedy/rspeedy.transformimport.md)                             | The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->. |

## Variables

| Variable                                               | Description |
| ------------------------------------------------------ | ----------- |
| [rspackVersion](/api/rspeedy/rspeedy.rspackversion.md) |             |
| [version](/api/rspeedy/rspeedy.version.md)             |             |

## Type Aliases

| Type Alias                                                                         | Description                                                                        |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [ConsoleType](/api/rspeedy/rspeedy.consoletype.md)                                 | The type of the console method.                                                    |
| [CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md)     | The style of exported class names.                                                 |
| [Entry](/api/rspeedy/rspeedy.entry.md)                                             | The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module. |
| [RsdoctorRspackPluginOptions](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md) |                                                                                    |
| [RspeedyInstance](/api/rspeedy/rspeedy.rspeedyinstance.md)                         | The instance of Rspeedy.                                                           |



---
url: /api/rspeedy/rspeedy.mergerspeedyconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [mergeRspeedyConfig](/api/rspeedy/rspeedy.mergerspeedyconfig.md)

## mergeRspeedyConfig() function

Merge multiple Rspeedy configuration objects.

**Signature:**

```typescript
export declare function mergeRspeedyConfig(...configs: Config[]): Config;
```

## Parameters

| Parameter | Type                                                | Description                                 |
| --------- | --------------------------------------------------- | ------------------------------------------- |
| configs   | [Config](/api/rspeedy/rspeedy.config.md)<!-- -->\[] | The Rspeedy configuration objects to merge. |

**Returns:**

[Config](/api/rspeedy/rspeedy.config.md)

The merged Rspeedy configuration object.

## Remarks

This is actually an alias of [mergeRsbuildConfig](https://rsbuild.dev/api/javascript-api/core#mergersbuildconfig)<!-- -->.

## Example

```ts
import { mergeRspeedyConfig } from '@lynx-js/rspeedy';

const config1 = {
  dev: {
    writeToDisk: false,
  },
};
const config2 = {
  dev: {
    writeToDisk: true,
  },
};

const mergedConfig = mergeRspeedyConfig(config1, config2);

console.log(mergedConfig); // { dev: { writeToDisk: true } }
```



---
url: /api/rspeedy/rspeedy.minify.css.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [css](/api/rspeedy/rspeedy.minify.css.md)

## Minify.css property

Whether enable the CSS minification.

**Signature:**

```typescript
css?: boolean | undefined;
```

## Remarks

When building for production, [@rsbuild/plugin-css-minimizer](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer) is used to minify CSS assets for better transmission efficiency.

## Example

- Disable the CSS minification.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      css: false,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.cssoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [cssOptions](/api/rspeedy/rspeedy.minify.cssoptions.md)

## Minify.cssOptions property

[Minify.cssOptions](/api/rspeedy/rspeedy.minify.cssoptions.md) is used to configure CSS minimizer options.

**Signature:**

```typescript
cssOptions?: Rspack.LightningCssMinimizerRspackPluginOptions | undefined;
```

## Remarks

For detailed configurations, please refer to [LightningCssMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/lightning-css-minimizer-rspack-plugin)<!-- -->.

## Example

- For example, disable error recovery:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      cssOptions: {
        minimizerOptions: {
          errorRecovery: false,
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.js.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [js](/api/rspeedy/rspeedy.minify.js.md)

## Minify.js property

Whether enable the JavaScript minification.

**Signature:**

```typescript
js?: boolean | undefined;
```

## Example

- Disable the JavaScript minification.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      js: false,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.jsoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md)

## Minify.jsOptions property

[Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) is used to configure SWC minification options.

**Signature:**

```typescript
jsOptions?: Rspack.SwcJsMinimizerRspackPluginOptions | undefined;
```

## Remarks

For detailed configurations, please refer to [SwcJsMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin)<!-- -->.

## Example

- Disable the mangle feature.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          mangle: false,
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md)

## Minify interface

The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.

**Signature:**

```typescript
export interface Minify 
```

## Properties

| Property                                               | Modifiers | Type                                                  | Description                                                                                                              |
| ------------------------------------------------------ | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [css?](/api/rspeedy/rspeedy.minify.css.md)             |           | boolean \| undefined                                  | _(Optional)_ Whether enable the CSS minification.                                                                        |
| [js?](/api/rspeedy/rspeedy.minify.js.md)               |           | boolean \| undefined                                  | _(Optional)_ Whether enable the JavaScript minification.                                                                 |
| [jsOptions?](/api/rspeedy/rspeedy.minify.jsoptions.md) |           | Rspack.SwcJsMinimizerRspackPluginOptions \| undefined | _(Optional)_ [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) is used to configure SWC minification options. |



---
url: /api/rspeedy/rspeedy.output.assetprefix.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md)

## Output.assetPrefix property

The [Output.assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md) is used to set the URL prefix for static assets.

**Signature:**

```typescript
assetPrefix?: string | undefined;
```

## Remarks

The functionality of [Output.assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md) is basically the same as the [output.publicPath](https://www.rspack.dev/config/output#outputpublicpath) config in Rspack. With the following differences:

- `output.assetPrefix` only takes effect in the production build.

- `output.assetPrefix` automatically appends a trailing `/` by default.

- The value of `output.assetPrefix` is written to the `process.env.ASSET_PREFIX` environment variable.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    assetPrefix: 'https://cdn.example.com/assets/',
  },
})
```



---
url: /api/rspeedy/rspeedy.output.cleandistpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [cleanDistPath](/api/rspeedy/rspeedy.output.cleandistpath.md)

## Output.cleanDistPath property

The [Output.cleanDistPath](/api/rspeedy/rspeedy.output.cleandistpath.md) option determines whether all files in the output directory (default: `dist`<!-- -->) are removed before the build starts.

**Signature:**

```typescript
cleanDistPath?: boolean | undefined;
```

## Remarks

By default, if the output directory is a subdirectory of the project root path, Rspeedy will automatically clean all files in the build directory.

When [output.distPath.root](https://rsbuild.dev/config/output/dist-path#root-directory) is an external directory or the same as the project root directory, `cleanDistPath` is not enabled by default to prevent accidental deletion of files from other directories.

## Example 1

- Disable cleaning files:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cleanDistPath: false,
  },
})
```

## Example 2

- Only clean files before the production build:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cleanDistPath: process.env.NODE_ENV === 'production',
  },
})
```



---
url: /api/rspeedy/rspeedy.output.copy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [copy](/api/rspeedy/rspeedy.output.copy.md)

## Output.copy property

The [Output.copy](/api/rspeedy/rspeedy.output.copy.md) option is used for copying files to the dist directory.

**Signature:**

```typescript
copy?: Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions['patterns'] | undefined;
```

## Remarks

For more options, see [Rspack.CopyRspackPlugin](https://rspack.dev/plugins/rspack/copy-rspack-plugin)<!-- -->.

## Example 1

- Copy files from `./src/assets` to the `./dist` directory:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    copy: [
      // `./src/assets/image.png` -> `./dist/image.png`
      { from: './src/assets' },
    ],
  },
})
```

## Example 2

- Copy files from ./src/assets to the ./dist/assets directory:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    copy: [
      // `./src/assets/image.png` -> `./dist/assets/image.png`
      { from: './src/assets', to: 'assets' },
    ],
  },
})
```



---
url: /api/rspeedy/rspeedy.output.cssmodules.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [cssModules](/api/rspeedy/rspeedy.output.cssmodules.md)

## Output.cssModules property

The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.

**Signature:**

```typescript
cssModules?: CssModules | undefined;
```

## Remarks

The CSS module is enabled for `*.module.css`<!-- -->, `*.module.scss` and `*.module.less`<!-- -->. Use [CssModules.auto](/api/rspeedy/rspeedy.cssmodules.auto.md) to customize the filtering behavior.

## Example 1

Disable CSS modules:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: false,
    },
  },
})
```

## Example 2

Enable CSS modules for all CSS files:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: () => true,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.output.dataurilimit.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [dataUriLimit](/api/rspeedy/rspeedy.output.dataurilimit.md)

## Output.dataUriLimit property

The [Output.dataUriLimit](/api/rspeedy/rspeedy.output.dataurilimit.md) option is used to set the size threshold to inline static assets such as images and fonts.

**Signature:**

```typescript
dataUriLimit?: number | DataUriLimit | undefined;
```

## Remarks

The default value of `dataUriLimit` is 2kB.

## Example 1

Inline all static assets less than 4kB:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    dataUriLimit: 4 * 1024,
  },
})
```

## Example 2

Disable inlining of static assets:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    dataUriLimit: 0,
  },
})
```

## Example 3

Inline all static assets:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    dataUriLimit: Number.MAX_SAFE_INTEGER,
  },
})
```

## Example 4

Disable inlining of all media but not images.

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    dataUriLimit: {
      image: 5000,
      media: 0,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.output.distpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [distPath](/api/rspeedy/rspeedy.output.distpath.md)

## Output.distPath property

Set the directory of the dist files.

**Signature:**

```typescript
distPath?: DistPath | undefined;
```

## Remarks

More options can be found at [Rsbuild - distPath](https://rsbuild.dev/config/output/dist-path)<!-- -->.

## Example

Use `output` instead of `dist`<!-- -->(the default value):

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    distPath: {
      root: './output',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.output.filename.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [filename](/api/rspeedy/rspeedy.output.filename.md)

## Output.filename property

The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.

**Signature:**

```typescript
filename?: string | Filename | undefined;
```

## Remarks

If a string is provided, it will be used as [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md)<!-- -->.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    filename: '[name]/[name].lynx.bundle',
  },
})
```



---
url: /api/rspeedy/rspeedy.output.filenamehash.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md)

## Output.filenameHash property

The [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md) option controls whether to add a hash value to the filename after the production build.

**Signature:**

```typescript
filenameHash?: boolean | string | undefined;
```

## Remarks

[Output.filename](/api/rspeedy/rspeedy.output.filename.md) has a higher priority than [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md)<!-- -->.

## Example 1

- Disable hash

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filenameHash: false,
  },
})
```

## Example 2

- Change hash format

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filenameHash: 'fullhash:16',
  },
})
```

The available hash formats are:

- `fullhash`<!-- -->: The hash value of the entire compilation. If any file changes, the hash values of all output files in the entire project will change.

- `chunkhash`<!-- -->: The hash value of the chunk. The hash value will only change when the content of the chunk (and its included modules) changes.

- `contenthash`<!-- -->: The hash value of the file content. The hash value will only change when the content of the file itself changes.



---
url: /api/rspeedy/rspeedy.output.inlinescripts.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [inlineScripts](/api/rspeedy/rspeedy.output.inlinescripts.md)

## Output.inlineScripts property

The [Output.inlineScripts](/api/rspeedy/rspeedy.output.inlinescripts.md) option controls whether to inline scripts into Lynx bundle (`.lynx.bundle`<!-- -->).

**Signature:**

```typescript
inlineScripts?: InlineChunkConfig | undefined;
```

## Remarks

If no value is provided, the default value would be `true`<!-- -->, which means all background thread scripts will be inlined.

This is different with [output.inlineScripts](https://rsbuild.dev/config/output/inline-scripts) since we normally want to inline scripts in Lynx bundle (`.lynx.bundle`<!-- -->).

There are two points that need to be especially noted:

1. Only background thread scripts can remain non-inlined, whereas the main thread script is always inlined.

2. Currently, when `experimental_isLazyBundle` is enabled, `inlineScripts` will always be `true`<!-- -->.

## Example

Disable inlining background thread scripts.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    inlineScripts: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.output.legalcomments.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [legalComments](/api/rspeedy/rspeedy.output.legalcomments.md)

## Output.legalComments property

The [Output.legalComments](/api/rspeedy/rspeedy.output.legalcomments.md) controls how to handle the legal comment.

**Signature:**

```typescript
legalComments?: 'none' | 'inline' | 'linked' | undefined;
```

## Remarks

If no value is provided, the default value would be `'none'`<!-- -->.

This is different with Rsbuild since we normally do not want a `.LEGAL.txt` file in Lynx outputs.

This behavior can be configured by using one of the following options:

- `linked`<!-- -->: Extract all legal comments to a `.LEGAL.txt` file and link to them with a comment.

- `inline`<!-- -->: Preserve all legal comments in original position.

- `none`<!-- -->: Remove all legal comments.



---
url: /api/rspeedy/rspeedy.output.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md)

## Output interface

The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.

**Signature:**

```typescript
export interface Output 
```

## Properties

| Property                                                       | Modifiers | Type                                                                                       | Description                                                                                                                                                                                                         |
| -------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [assetPrefix?](/api/rspeedy/rspeedy.output.assetprefix.md)     |           | string \| undefined                                                                        | _(Optional)_ The [Output.assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md) is used to set the URL prefix for static assets.                                                                                  |
| [cleanDistPath?](/api/rspeedy/rspeedy.output.cleandistpath.md) |           | boolean \| undefined                                                                       | _(Optional)_ The [Output.cleanDistPath](/api/rspeedy/rspeedy.output.cleandistpath.md) option determines whether all files in the output directory (default: <code>dist</code>) are removed before the build starts. |
| [copy?](/api/rspeedy/rspeedy.output.copy.md)                   |           | Rspack.CopyRspackPluginOptions \| Rspack.CopyRspackPluginOptions\['patterns'] \| undefined | _(Optional)_ The [Output.copy](/api/rspeedy/rspeedy.output.copy.md) option is used for copying files to the dist directory.                                                                                         |
| [cssModules?](/api/rspeedy/rspeedy.output.cssmodules.md)       |           | [CssModules](/api/rspeedy/rspeedy.cssmodules.md) \| undefined                              | _(Optional)_ The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.                                                                               |
| [dataUriLimit?](/api/rspeedy/rspeedy.output.dataurilimit.md)   |           | number \| DataUriLimit \| undefined                                                        | _(Optional)_ The [Output.dataUriLimit](/api/rspeedy/rspeedy.output.dataurilimit.md) option is used to set the size threshold to inline static assets such as images and fonts.                                      |
| [distPath?](/api/rspeedy/rspeedy.output.distpath.md)           |           | [DistPath](/api/rspeedy/rspeedy.distpath.md) \| undefined                                  | _(Optional)_ Set the directory of the dist files.                                                                                                                                                                   |
| [filename?](/api/rspeedy/rspeedy.output.filename.md)           |           | string \| [Filename](/api/rspeedy/rspeedy.filename.md) \| undefined                        | _(Optional)_ The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.              |
| [filenameHash?](/api/rspeedy/rspeedy.output.filenamehash.md)   |           | boolean \| string \| undefined                                                             | _(Optional)_ The [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md) option controls whether to add a hash value to the filename after the production build.                                         |
| [inlineScripts?](/api/rspeedy/rspeedy.output.inlinescripts.md) |           | InlineChunkConfig \| undefined                                                             | _(Optional)_ The [Output.inlineScripts](/api/rspeedy/rspeedy.output.inlinescripts.md) option controls whether to inline scripts into Lynx bundle (<code>.lynx.bundle</code>).                                       |
| [legalComments?](/api/rspeedy/rspeedy.output.legalcomments.md) |           | 'none' \| 'inline' \| 'linked' \| undefined                                                | _(Optional)_ The [Output.legalComments](/api/rspeedy/rspeedy.output.legalcomments.md) controls how to handle the legal comment.                                                                                     |
| [minify?](/api/rspeedy/rspeedy.output.minify.md)               |           | [Minify](/api/rspeedy/rspeedy.minify.md) \| boolean \| undefined                           | _(Optional)_ The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.                                                |
| [sourceMap?](/api/rspeedy/rspeedy.output.sourcemap.md)         |           | boolean \| [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) \| undefined                     | _(Optional)_ The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.                                                                                      |



---
url: /api/rspeedy/rspeedy.output.minify.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [minify](/api/rspeedy/rspeedy.output.minify.md)

## Output.minify property

The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.

**Signature:**

```typescript
minify?: Minify | boolean | undefined;
```

## Example

Disable minification.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    minify: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.output.sourcemap.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [sourceMap](/api/rspeedy/rspeedy.output.sourcemap.md)

## Output.sourceMap property

The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

**Signature:**

```typescript
sourceMap?: boolean | SourceMap | undefined;
```



---
url: /api/rspeedy/rspeedy.performance.buildcache.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [buildCache](/api/rspeedy/rspeedy.performance.buildcache.md)

## Performance.buildCache property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Enable or configure persistent build cache.

This feature is experimental and may be changed in the future.

**Signature:**

```typescript
buildCache?: BuildCache | boolean | undefined;
```

## Example 1

Enable persistent build cache.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: true,
  },
})
```

## Example 2

Customize build cache.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: {
      cacheDigest: [process.env.SOME_ENV],
      buildDependencies: ['postcss.config.js'],
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.performance.chunksplit.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md)

## Performance.chunkSplit property

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
chunkSplit?: ChunkSplit | ChunkSplitBySize | ChunkSplitCustom | undefined;
```



---
url: /api/rspeedy/rspeedy.performance.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md)

## Performance interface

The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.

**Signature:**

```typescript
export interface Performance 
```

## Properties

| Property                                                            | Modifiers | Type                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [buildCache?](/api/rspeedy/rspeedy.performance.buildcache.md)       |           | [BuildCache](/api/rspeedy/rspeedy.buildcache.md) \| boolean \| undefined                                                                                                                      | <p>**_(BETA)_** _(Optional)_ Enable or configure persistent build cache.</p><p>This feature is experimental and may be changed in the future.</p>                                                                                                                                     |
| [chunkSplit?](/api/rspeedy/rspeedy.performance.chunksplit.md)       |           | [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md) \| [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) \| [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md) \| undefined | _(Optional)_ [Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.                                                                                                                                              |
| [printFileSize?](/api/rspeedy/rspeedy.performance.printfilesize.md) |           | PerformanceConfig\['printFileSize'] \| undefined                                                                                                                                              | <p>_(Optional)_ Whether to print the file sizes after production build.</p><p>[Performance.printFileSize](/api/rspeedy/rspeedy.performance.printfilesize.md)</p><p>See [Rsbuild - performance.printFileSize](https://rsbuild.dev/config/performance/print-file-size) for details.</p> |
| [profile?](/api/rspeedy/rspeedy.performance.profile.md)             |           | boolean \| undefined                                                                                                                                                                          | _(Optional)_ Whether capture timing information in the build time and the runtime, the same as the [profile](https://rspack.dev/config/other-options#profile) config of Rspack.                                                                                                       |
| [removeConsole?](/api/rspeedy/rspeedy.performance.removeconsole.md) |           | boolean \| [ConsoleType](/api/rspeedy/rspeedy.consoletype.md)<!-- -->\[] \| undefined                                                                                                         | _(Optional)_ Whether to remove <code>console.\[methodName]</code> in production build.                                                                                                                                                                                                |



---
url: /api/rspeedy/rspeedy.performance.printfilesize.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [printFileSize](/api/rspeedy/rspeedy.performance.printfilesize.md)

## Performance.printFileSize property

Whether to print the file sizes after production build.

[Performance.printFileSize](/api/rspeedy/rspeedy.performance.printfilesize.md)

See [Rsbuild - performance.printFileSize](https://rsbuild.dev/config/performance/print-file-size) for details.

**Signature:**

```typescript
printFileSize?: PerformanceConfig['printFileSize'] | undefined;
```

## Example 1

If you don't want to print any information, you can disable it by setting printFileSize to false:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: false
  },
})
```

## Example 2

Set total to false to disable total size output.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      total: false,
    },
  },
})
```

## Example 3

Set detail to false to disable per-asset size output.

If you don't need to view the size of each static asset, you can set detail to false. In this case, only the total size will be output:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      detail: false,
    },
  },
})
```

## Example 4

If you don't need to view the gzipped size, you can set compressed to false. This can save some gzip computation time for large projects:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      compressed: false,
    },
  },
})
```

## Example 5

To include only static assets that meet certain criteria, use a filter function with include.

If returned false, the static asset will be excluded and not included in the total size or detailed size.

only output static assets larger than 10kB:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      include: (asset) => asset.size > 10 * 1000,
    }
  },
})
```

## Example 6

To exclude static assets that meet certain criteria, use a filter function with exclude. If both include and exclude are set, exclude will take precedence.

Rspeedy defaults to excluding source map, license files, and .d.ts type files, as these files do not affect page load performance.

exclude .html files in addition to the default:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      exclude: (asset) =>
        /\.(?:map|LICENSE\.txt)$/.test(asset.name) ||
        /\.html$/.test(asset.name),
    }
  },
})
```



---
url: /api/rspeedy/rspeedy.performance.profile.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [profile](/api/rspeedy/rspeedy.performance.profile.md)

## Performance.profile property

Whether capture timing information in the build time and the runtime, the same as the [profile](https://rspack.dev/config/other-options#profile) config of Rspack.

**Signature:**

```typescript
profile?: boolean | undefined;
```

## Remarks

This option would be `true` when `DEBUG` environment variable contains `rspeedy`<!-- -->.

## Example

Enable profile.

- Rsbuild will auto-generate `dist/stats.json` file through bundle analyzer.

- Rspack will include the build time information when generating `stats.json`<!-- -->.

- Frameworks like ReactLynx will include runtime information using `console.profile`<!-- -->.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: { profile: true },
})
```



---
url: /api/rspeedy/rspeedy.performance.removeconsole.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [removeConsole](/api/rspeedy/rspeedy.performance.removeconsole.md)

## Performance.removeConsole property

Whether to remove `console.[methodName]` in production build.

**Signature:**

```typescript
removeConsole?: boolean | ConsoleType[] | undefined;
```

## Example 1

- Remove all `console` methods

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    removeConsole: true,
  },
})
```

## Example 2

- Remove specific `console` methods

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    removeConsole: ['log', 'warn']
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.alias.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [alias](/api/rspeedy/rspeedy.resolve.alias.md)

## Resolve.alias property

Create aliases to `import` or `require` certain modules more easily.

**Signature:**

```typescript
alias?: Record<string, string | false | string[]> | undefined;
```

## Example 1

A trailing `$` can also be added to the given object's keys to signify an exact match:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  resolve: {
    alias: {
      xyz$: 'path/to/file.js',
    },
  },
})
```

which would yield these results:

```js
import Test1 from 'xyz'; // Exact match, so path/to/file.js is resolved and imported
import Test2 from 'xyz/file.js'; // Not an exact match, normal resolution takes place
```

## Example 2

`resolve.alias` is useful to control how a npm package is resolved.

- Change `react` to `@lynx-js/react`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { createRequire } from 'module'
const require = createRequire(import.meta.url)
export default defineConfig({
  resolve: {
    alias: {
      react: require.resolve('@lynx-js/react'),
    },
  },
})
```

This allows you to use some third-party libraries that directly uses `react` as dependencies in ReactLynx.

- Force using the same version of `dayjs`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { createRequire } from 'module'
const require = createRequire(import.meta.url)
export default defineConfig({
  resolve: {
    alias: {
      dayjs: require.resolve('dayjs'),
    },
  },
})
```

Please note that this is dangerous, since all the `dayjs`<!-- -->(including the dependencies of a dependencies) is resolved to the version in the project. It may cause both compile-time and runtime errors due to version mismatch.

## Example 3

Setting `resolve.alias` to `false` will ignore a module.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  resolve: {
    alias: {
      'ignored-module': false,
      './ignored-module': false,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.aliasstrategy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [aliasStrategy](/api/rspeedy/rspeedy.resolve.aliasstrategy.md)

## Resolve.aliasStrategy property

Set the strategy for path alias resolution, to control the priority relationship between the `paths` option in `tsconfig.json` and the `resolve.alias` option of Rsbuild. - `prefer-tsconfig` (default): The `paths` option in `tsconfig.json` will take precedence over the `resolve.alias` option of Rsbuild. - `prefer-alias`<!-- -->: The `resolve.alias` option of Rsbuild will take precedence over the `paths` option in `tsconfig.json`<!-- -->.

**Signature:**

```typescript
aliasStrategy?: 'prefer-tsconfig' | 'prefer-alias' | undefined;
```

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  resolve: {
    alias: {
      '@': './src',
    },
    aliasStrategy: 'prefer-alias',
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.dedupe.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [dedupe](/api/rspeedy/rspeedy.resolve.dedupe.md)

## Resolve.dedupe property

Force to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.

**Signature:**

```typescript
dedupe?: string[] | undefined;
```

## Remarks

[Resolve.dedupe](/api/rspeedy/rspeedy.resolve.dedupe.md) is implemented based on [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md)<!-- -->, it will get the path of the specified package through `require.resolve` in the project root directory and set it to the alias.

The alias generated by [Resolve.dedupe](/api/rspeedy/rspeedy.resolve.dedupe.md) will be merged with the configured [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md) in the project, and the [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md) config will take precedence when the keys are the same.

## Example

Use `tslib` from the project root directory.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  resolve: {
    dedupe: ['tslib'],
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.extensions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [extensions](/api/rspeedy/rspeedy.resolve.extensions.md)

## Resolve.extensions property

Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.

Default: `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json', '.cjs']`

For example, if importing './index', Rsbuild will try to resolve using the following order:

- `./index.ts`

- `./index.tsx`

- `./index.mjs`

- `./index.js`

- `./index.jsx`

- `./index.json`

- `./index.cjs`

**Signature:**

```typescript
extensions?: string[] | undefined;
```

## Remarks

The difference between `resolve.extensions` and `tools.rspack.resolve.extensions`<!-- -->:

`resolve.extensions`<!-- -->: Completely overrides Rspeedy's default resolution.

`tools.rspack.resolve.extensions`<!-- -->: Merges with the default configuration using \[`webpack-merge`<!-- -->]\([https://github.com/survivejs/webpack-merge](https://github.com/survivejs/webpack-merge)).

## Example

```js
export default {
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
  },
}
```



---
url: /api/rspeedy/rspeedy.resolve.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md)

## Resolve interface

The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.

**Signature:**

```typescript
export interface Resolve 
```

## Properties

| Property                                                        | Modifiers | Type                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [alias?](/api/rspeedy/rspeedy.resolve.alias.md)                 |           | Record\<string, string \| false \| string\[]> \| undefined | _(Optional)_ Create aliases to <code>import</code> or <code>require</code> certain modules more easily.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [aliasStrategy?](/api/rspeedy/rspeedy.resolve.aliasstrategy.md) |           | 'prefer-tsconfig' \| 'prefer-alias' \| undefined           | _(Optional)_ Set the strategy for path alias resolution, to control the priority relationship between the <code>paths</code> option in <code>tsconfig.json</code> and the <code>resolve.alias</code> option of Rsbuild. - <code>prefer-tsconfig</code> (default): The <code>paths</code> option in <code>tsconfig.json</code> will take precedence over the <code>resolve.alias</code> option of Rsbuild. - <code>prefer-alias</code>: The <code>resolve.alias</code> option of Rsbuild will take precedence over the <code>paths</code> option in <code>tsconfig.json</code>.              |
| [dedupe?](/api/rspeedy/rspeedy.resolve.dedupe.md)               |           | string\[] \| undefined                                     | _(Optional)_ Force to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [extensions?](/api/rspeedy/rspeedy.resolve.extensions.md)       |           | string\[] \| undefined                                     | <p>_(Optional)_ Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.</p><p>Default: <code>\['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json', '.cjs']</code></p><p>For example, if importing './index', Rsbuild will try to resolve using the following order:</p><p>- <code>./index.ts</code></p><p>- <code>./index.tsx</code></p><p>- <code>./index.mjs</code></p><p>- <code>./index.js</code></p><p>- <code>./index.jsx</code></p><p>- <code>./index.json</code></p><p>- <code>./index.cjs</code></p> |



---
url: /api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [RsdoctorRspackPluginOptions](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md)

## RsdoctorRspackPluginOptions type

**Signature:**

```typescript
export type RsdoctorRspackPluginOptions = ConstructorParameters<typeof RsdoctorRspackPlugin<[]>>[0];
```



---
url: /api/rspeedy/rspeedy.rspackversion.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [rspackVersion](/api/rspeedy/rspeedy.rspackversion.md)

## rspackVersion variable

**Signature:**

```typescript
rspackVersion: string
```



---
url: /api/rspeedy/rspeedy.rspeedyinstance.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [RspeedyInstance](/api/rspeedy/rspeedy.rspeedyinstance.md)

## RspeedyInstance type

The instance of Rspeedy.

**Signature:**

```typescript
export type RspeedyInstance = RsbuildInstance & {
    getRspeedyConfig(): Config;
};
```

**References:** [Config](/api/rspeedy/rspeedy.config.md)



---
url: /api/rspeedy/rspeedy.server.base.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [base](/api/rspeedy/rspeedy.server.base.md)

## Server.base property

Configure the base path of the server.

**Signature:**

```typescript
base?: string | undefined;
```

## Remarks

By default, the base path of the server is `/`<!-- -->, and users can access lynx bundle through `http://<host>:<port>/main.lynx.bundle`

If you want to access lynx bundle through `http://<host>:<port>/foo/main.lynx.bundle`<!-- -->, you can change `server.base` to `/foo`

you can refer to [server.base](https://rsbuild.dev/config/server/base) for more information.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    base: '/dist'
  },
})
```



---
url: /api/rspeedy/rspeedy.server.compress.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [compress](/api/rspeedy/rspeedy.server.compress.md)

## Server.compress property

Configure whether to enable [gzip compression](https://developer.mozilla.org/en-US/docs/Glossary/gzip_compression) for static assets served by the dev server or preview server.

Default: true

See [Rsbuild - server.compress](https://rsbuild.rs/config/server/compress) for details.

**Signature:**

```typescript
compress?: boolean | CompressOptions | undefined;
```

## Example 1

To disable the gzip compression, set compress to false:

```js
export default {
  server: {
    compress: false,
  },
}
```

## Example 2

Compress if it starts with /foo

```js
export default {
  server: {
    compress: {
      filter: (req) => {
        if (req.url?.includes('/foo')) {
          return false;
        }
        return true;
      },
    },
  },
}
```

## Example 3

set level of zlib compression

```js
export default {
  server: {
    compress: {
      level: 6,
    },
  },
}
```



---
url: /api/rspeedy/rspeedy.server.cors.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [cors](/api/rspeedy/rspeedy.server.cors.md)

## Server.cors property

Configure CORS for the dev server or preview server.

- Set to an object to enable CORS with the specified options.

- Set to `true` to enable CORS with the default options (allows all origins, not recommended).

- Set to `false` to disable CORS.

See [Rsbuild - server.cors](https://rsbuild.rs/config/server/cors) for details.

**Signature:**

```typescript
cors?: ServerConfig['cors'] | undefined;
```

## Example

```js
export default {
  server: {
    cors: {
      origin: 'https://example.com',
    },
  },
}
```



---
url: /api/rspeedy/rspeedy.server.headers.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [headers](/api/rspeedy/rspeedy.server.headers.md)

## Server.headers property

Adds headers to all responses.

**Signature:**

```typescript
headers?: Record<string, string | string[]> | undefined;
```

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    headers: {
      'Access-Control-Allow-Origin': '**',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.server.host.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [host](/api/rspeedy/rspeedy.server.host.md)

## Server.host property

Specify the host that the Rspeedy Server listens to.

**Signature:**

```typescript
host?: string | undefined;
```

## Remarks

By default, the server listens on local network IP, for example, `192.168.1.50`<!-- -->, verify your local net IP by the command `ifconfig` on your system for (en0 for MacOS and eth0 for LinuxOS users). In case you have multiple local network IP(s) particularly when you are running dockers on the host machine, then you can specify your desired host IP.

## Example

Set the host to a custom value:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    host: "192.168.1.50",
  },
})
```



---
url: /api/rspeedy/rspeedy.server.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md)

## Server interface

The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.

**Signature:**

```typescript
export interface Server 
```

## Properties

| Property                                                 | Modifiers | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------- | --------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [base?](/api/rspeedy/rspeedy.server.base.md)             |           | string \| undefined                               | _(Optional)_ Configure the base path of the server.                                                                                                                                                                                                                                                                                                                                                   |
| [compress?](/api/rspeedy/rspeedy.server.compress.md)     |           | boolean \| CompressOptions \| undefined           | <p>_(Optional)_ Configure whether to enable [gzip compression](https://developer.mozilla.org/en-US/docs/Glossary/gzip_compression) for static assets served by the dev server or preview server.</p><p>Default: true</p><p>See [Rsbuild - server.compress](https://rsbuild.rs/config/server/compress) for details.</p>                                                                                |
| [cors?](/api/rspeedy/rspeedy.server.cors.md)             |           | ServerConfig\['cors'] \| undefined                | <p>_(Optional)_ Configure CORS for the dev server or preview server.</p><p>- Set to an object to enable CORS with the specified options.</p><p>- Set to <code>true</code> to enable CORS with the default options (allows all origins, not recommended).</p><p>- Set to <code>false</code> to disable CORS.</p><p>See [Rsbuild - server.cors](https://rsbuild.rs/config/server/cors) for details.</p> |
| [headers?](/api/rspeedy/rspeedy.server.headers.md)       |           | Record\<string, string \| string\[]> \| undefined | _(Optional)_ Adds headers to all responses.                                                                                                                                                                                                                                                                                                                                                           |
| [host?](/api/rspeedy/rspeedy.server.host.md)             |           | string \| undefined                               | _(Optional)_ Specify the host that the Rspeedy Server listens to.                                                                                                                                                                                                                                                                                                                                     |
| [port?](/api/rspeedy/rspeedy.server.port.md)             |           | number \| undefined                               | _(Optional)_ Specify the port that the Rspeedy Server listens to.                                                                                                                                                                                                                                                                                                                                     |
| [proxy?](/api/rspeedy/rspeedy.server.proxy.md)           |           | ProxyConfig \| undefined                          | _(Optional)_ Configure proxy rules for the dev server or preview server to proxy requests to the specified service.                                                                                                                                                                                                                                                                                   |
| [strictPort?](/api/rspeedy/rspeedy.server.strictport.md) |           | boolean \| undefined                              | <p>_(Optional)_ When a port is occupied, Rspeedy will automatically increment the port number until an available port is found.</p><p>Set strictPort to true and Rspeedy will throw an exception when the port is occupied.</p>                                                                                                                                                                       |



---
url: /api/rspeedy/rspeedy.server.port.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [port](/api/rspeedy/rspeedy.server.port.md)

## Server.port property

Specify the port that the Rspeedy Server listens to.

**Signature:**

```typescript
port?: number | undefined;
```

## Remarks

By default, the server listens on port `3000` and automatically increments the port number when the port is occupied.

## Example

Set the port to a custom value:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    port: 3470,
  },
})
```



---
url: /api/rspeedy/rspeedy.server.proxy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [proxy](/api/rspeedy/rspeedy.server.proxy.md)

## Server.proxy property

Configure proxy rules for the dev server or preview server to proxy requests to the specified service.

**Signature:**

```typescript
proxy?: ProxyConfig | undefined;
```

## Example

```js
export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> http://localhost:3000/api
      // http://localhost:3000/api/foo -> http://localhost:3000/api/foo
      '/api': 'http://localhost:3000',
    },
  },
}
```



---
url: /api/rspeedy/rspeedy.server.strictport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [strictPort](/api/rspeedy/rspeedy.server.strictport.md)

## Server.strictPort property

When a port is occupied, Rspeedy will automatically increment the port number until an available port is found.

Set strictPort to true and Rspeedy will throw an exception when the port is occupied.

**Signature:**

```typescript
strictPort?: boolean | undefined;
```



---
url: /api/rspeedy/rspeedy.source.alias.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [alias](/api/rspeedy/rspeedy.source.alias.md)

## Source.alias property

> Warning: This API is now obsolete.
>
> - Use [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md) instead.

Create aliases to `import` or `require` certain modules more easily.

**Signature:**

```typescript
alias?: Record<string, string | false | string[]> | undefined;
```



---
url: /api/rspeedy/rspeedy.source.assetsinclude.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [assetsInclude](/api/rspeedy/rspeedy.source.assetsinclude.md)

## Source.assetsInclude property

Include additional files that should be treated as static assets. Defaults to be `undefined`<!-- -->.

**Signature:**

```typescript
assetsInclude?: Rspack.RuleSetCondition | undefined;
```

## Remarks

By default, Rsbuild treats common image, font, audio, and video files as static assets. Through the source.assetsInclude config, you can specify additional file types that should be treated as static assets. These added static assets are processed using the same rules as the built-in supported static assets。

The usage of `source.assetsInclude` is consistent with [Condition](https://rspack.dev/config/module#condition) in Rspack, which supports passing in strings, regular expressions, arrays of conditions, or logical conditions to match the module path or assets.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    assetsInclude: /\.json5$/,
  },
})
```



---
url: /api/rspeedy/rspeedy.source.decorators.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [decorators](/api/rspeedy/rspeedy.source.decorators.md)

## Source.decorators property

Used to configure the decorators syntax.

**Signature:**

```typescript
decorators?: Decorators | undefined;
```

## Remarks

See [Decorators.version](/api/rspeedy/rspeedy.decorators.version.md) for more information.



---
url: /api/rspeedy/rspeedy.source.define.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [define](/api/rspeedy/rspeedy.source.define.md)

## Source.define property

The `define` options is used to define some values or expressions at compile time.

**Signature:**

```typescript
define?: Record<string, string | number | boolean | undefined | Record<string, unknown>> | undefined;
```

## Remarks

- If the value provided is a string, it will be utilized as a code fragment.

- If the value provided is an object, all its keys will be defined in the same manner.

- If the value isn't a string, it will be stringified, with functions included.

- Notably, if a `typeof` prefix is attached to the key, it will be exclusively defined for `typeof` calls."

## Example 1

Using `define` for environment variables.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      BUILD_VERSION: JSON.stringify(process.env.BUILD_VERSION ?? 'unknown_version'),
      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
    },
  },
})
```

Expressions will be replaced with the corresponding code fragments:

```js
const version = BUILD_VERSION;
if (process.env.NODE_ENV === 'development') {}

// ⬇️ Turn into being...
const version = "unknown_version";
if ("development" === 'development') {}
```

## Example 2

Using `define` for `typeof`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      'typeof window': JSON.stringify("undefined"),
    },
  },
})
```

The `typeof` expressions will be replaced with the corresponding code fragments:

```js
if (typeof window !== 'undefined') {}

// ⬇️ Turn into being...
if ("undefined" !== 'undefined') {}
```

## Example 3

Using `define` with objects.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      'import.meta': {
        foo: JSON.stringify('foo'),
        bar: { baz: 0 },
      },
    },
  },
})
```

Expressions will be replaced with the corresponding code fragments:

```js
console.log(import.meta)

// ⬇️ Turn into being...
console.log({ foo: "foo", bar: { baz: 0 } })
```



---
url: /api/rspeedy/rspeedy.source.entry.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [entry](/api/rspeedy/rspeedy.source.entry.md)

## Source.entry property

The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module.

**Signature:**

```typescript
entry?: Entry | undefined;
```

## Remarks

If no value is provided, the default value `'./src/index.js'` will be used.

## Example 1

- Use a single entry:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: './src/pages/main/index.js',
  },
})
```

## Example 2

- Use a single entry with multiple entry modules:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: ['./src/prefetch.js', './src/pages/main/index.js'],
  },
})
```

## Example 3

- Use multiple entries(with multiple entry modules):

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: ['./src/pages/bar/index.js', './src/post.js'], // multiple entry modules is allowed
    },
  },
})
```

## Example 4

- Use multiple entries with [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: {
        import: ['./src/prefetch.js', './src/pages/bar'],
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.source.exclude.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [exclude](/api/rspeedy/rspeedy.source.exclude.md)

## Source.exclude property

The `source.exclude` is used to specify JavaScript files that should be excluded from compilation.

**Signature:**

```typescript
exclude?: Rspack.RuleSetCondition[] | undefined;
```

## Remarks

By default, Rsbuild compiles JavaScript files in the current directory and TypeScript/JSX files in all directories. Through the `source.exclude` config, you can specify files or directories that should be excluded from compilation. The usage of `source.exclude` is consistent with [Rule.exclude](https://rspack.dev/config/module#ruleexclude) in Rspack, which supports passing in strings or regular expressions to match module paths.

## Example 1

- Exclude specific files or directories

You can exclude specific files or directories from compilation to improve build performance or avoid processing certain files:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    exclude: [
      // Exclude all files in the test directory
      /[\\/]test[\\/]/,
      // Exclude specific file
      './src/legacy-file.js',
      // Exclude files matching a pattern
      /\.stories\.(js|ts)x?$/,
    ],
  },
})
```

## Example 2

- Exclude third-party dependencies

You can exclude specific third-party dependencies that don't need compilation:

```js
import { defineConfig } from '@lynx-js/rspeedy'
import path from 'node:path'
import { createRequire } from 'node:module'

const require = createRequire(import.meta.url)

export default defineConfig({
  source: {
    exclude: [
      // Exclude specific package
      path.dirname(require.resolve('lodash')),
      // Exclude using regex pattern
      /node_modules[\\/]lodash-es[\\/]/,
    ],
  },
})
```



---
url: /api/rspeedy/rspeedy.source.include.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [include](/api/rspeedy/rspeedy.source.include.md)

## Source.include property

The `source.include` is used to specify additional JavaScript files that need to be compiled.

**Signature:**

```typescript
include?: Rspack.RuleSetCondition[] | undefined;
```

## Remarks

To avoid redundant compilation, by default, Rsbuild only compiles JavaScript files in the current directory and TypeScript and JSX files in all directories. It does not compile JavaScript files under `node_modules`<!-- -->.

Through the `source.include` config, you can specify directories or modules that need to be compiled by Rsbuild. The usage of `source.include` is consistent with [Rule.include](https://rspack.dev/config/module#ruleinclude) in Rspack, which supports passing in strings or regular expressions to match the module path.

## Example 1

- Compile Npm Packages

A typical usage scenario is to compile npm packages under `node_modules`<!-- -->, because some third-party dependencies have ESNext syntax, which may not be supported in Lynx. You can solve the problem by using this config to specify the dependencies that need to be compiled.

```js
import { createRequire } from 'node:module'
import path from 'node:path'

import { defineConfig } from '@lynx-js/rspeedy'

const require = createRequire(import.meta.url)

export default defineConfig({
  source: {
    include: [
      // Method 1:
      // First get the path of the module by `require.resolve`
      // Then pass path.dirname to point to the corresponding directory
      path.dirname(require.resolve('query-string')),
      // Method 2:
      // Match by regular expression
      // All paths containing `node_modules/query-string/` will be matched
      /node_modules[\\/]query-string[\\/]/,
    ],
  },
})
```

## Example 2

- Compile Libraries in Monorepo

```js
import path from 'node:path'
import { fileURLToPath } from 'node:url'

import { defineConfig } from '@lynx-js/rspeedy'

const __dirname = path.dirname(fileURLToPath(import.meta.url))

const packagesDir = path.resolve(__dirname, '../../packages')

export default defineConfig({
  source: {
    include: [
      // Compile all files in Monorepo's package directory
      // It is recommended to exclude the node_modules
      {
        and: [packagesDir, { not: /[\\/]node_modules[\\/]/ }],
      },
    ],
  },
})
```



---
url: /api/rspeedy/rspeedy.source.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md)

## Source interface

The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.

**Signature:**

```typescript
export interface Source 
```

## Properties

| Property                                                           | Modifiers | Type                                                                                               | Description                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [alias?](/api/rspeedy/rspeedy.source.alias.md)                     |           | Record\<string, string \| false \| string\[]> \| undefined                                         | _(Optional)_ Create aliases to <code>import</code> or <code>require</code> certain modules more easily.                                                                                                                                                                                                |
| [assetsInclude?](/api/rspeedy/rspeedy.source.assetsinclude.md)     |           | Rspack.RuleSetCondition \| undefined                                                               | _(Optional)_ Include additional files that should be treated as static assets. Defaults to be <code>undefined</code>.                                                                                                                                                                                  |
| [decorators?](/api/rspeedy/rspeedy.source.decorators.md)           |           | [Decorators](/api/rspeedy/rspeedy.decorators.md) \| undefined                                      | _(Optional)_ Used to configure the decorators syntax.                                                                                                                                                                                                                                                  |
| [define?](/api/rspeedy/rspeedy.source.define.md)                   |           | Record\<string, string \| number \| boolean \| undefined \| Record\<string, unknown>> \| undefined | _(Optional)_ The <code>define</code> options is used to define some values or expressions at compile time.                                                                                                                                                                                             |
| [entry?](/api/rspeedy/rspeedy.source.entry.md)                     |           | [Entry](/api/rspeedy/rspeedy.entry.md) \| undefined                                                | _(Optional)_ The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module.                                                                                                                                                                                                        |
| [exclude?](/api/rspeedy/rspeedy.source.exclude.md)                 |           | Rspack.RuleSetCondition\[] \| undefined                                                            | _(Optional)_ The <code>source.exclude</code> is used to specify JavaScript files that should be excluded from compilation.                                                                                                                                                                             |
| [include?](/api/rspeedy/rspeedy.source.include.md)                 |           | Rspack.RuleSetCondition\[] \| undefined                                                            | _(Optional)_ The <code>source.include</code> is used to specify additional JavaScript files that need to be compiled.                                                                                                                                                                                  |
| [preEntry?](/api/rspeedy/rspeedy.source.preentry.md)               |           | string \| string\[] \| undefined                                                                   | _(Optional)_ Add a script before the entry file of each page. This script will be executed before the page code. It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.                                                                                     |
| [transformImport?](/api/rspeedy/rspeedy.source.transformimport.md) |           | [TransformImport](/api/rspeedy/rspeedy.transformimport.md)<!-- -->\[] \| undefined                 | _(Optional)_ The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->. |
| [tsconfigPath?](/api/rspeedy/rspeedy.source.tsconfigpath.md)       |           | string \| undefined                                                                                | _(Optional)_ Configure a custom <code>tsconfig.json</code> file path to use, can be a relative or absolute path. Defaults to be <code>./tsconfig.json</code>.                                                                                                                                          |



---
url: /api/rspeedy/rspeedy.source.preentry.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [preEntry](/api/rspeedy/rspeedy.source.preentry.md)

## Source.preEntry property

Add a script before the entry file of each page. This script will be executed before the page code. It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.

**Signature:**

```typescript
preEntry?: string | string[] | undefined;
```

## Remarks

See [source.preEntry](https://rsbuild.dev/config/source/pre-entry) for more details.

## Example

Relative path will be resolved relative to the project root directory.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    preEntry: './src/polyfill.ts',
  },
})
```



---
url: /api/rspeedy/rspeedy.source.transformimport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [transformImport](/api/rspeedy/rspeedy.source.transformimport.md)

## Source.transformImport property

The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->.

**Signature:**

```typescript
transformImport?: TransformImport[] | undefined;
```

## Example

When using the TUX component library, you can import components on demand with the following config:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    transformImport: [
      {
        libraryName: 'foo',
        customName: 'foo/src/components/{{ member }}/{{ member }}',
      },
    ],
  },
})
```

This will transform the following source code:

```js
import { Button } from 'foo'
```

to:

```js
import { Button } from 'foo/src/components/Button/Button'
```



---
url: /api/rspeedy/rspeedy.source.tsconfigpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [tsconfigPath](/api/rspeedy/rspeedy.source.tsconfigpath.md)

## Source.tsconfigPath property

Configure a custom `tsconfig.json` file path to use, can be a relative or absolute path. Defaults to be `./tsconfig.json`<!-- -->.

**Signature:**

```typescript
tsconfigPath?: string | undefined;
```

## Remarks

The `tsconfigPath` configuration affects the following behaviors:

- The `paths` field is used to configure [Path Aliases](/api/rspeedy/rspeedy.source.alias.md)<!-- -->.

- Sets the scope and rules for the [Type Check Plugin](https://rsbuild.rs/guide/basic/typescript#type-checking)<!-- -->.

## Example

Relative path will be resolved relative to the project root directory.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    tsconfigPath: './tsconfig.build.json',
  },
})
```



---
url: /api/rspeedy/rspeedy.sourcemap.js.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) > [js](/api/rspeedy/rspeedy.sourcemap.js.md)

## SourceMap.js property

How the source map should be generated. Setting it to `false` will disable the source map.

**Signature:**

```typescript
js?: Rspack.DevTool | undefined | `${Exclude<Rspack.DevTool, false | 'eval'>}-debugids`;
```

## Remarks

Defaults to `'cheap-module-source-map'` at development, `false` at production.

See [Rspack - Devtool](https://rspack.dev/config/devtool) for details.

## Example 1

- Enable high-quality source-maps for production:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    sourceMap: {
      js: process.env['NODE_ENV'] === 'production'
        ? 'source-map'
        : 'cheap-module-source-map',
    },
  },
})
```

## Example 2

- Disable source-map generation:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    sourceMap: {
      js: false,
    },
  },
})
```

## Example 3

- Use high-quality source-maps for all environments:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    sourceMap: {
      js: 'source-map',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.sourcemap.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [SourceMap](/api/rspeedy/rspeedy.sourcemap.md)

## SourceMap interface

The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

**Signature:**

```typescript
export interface SourceMap 
```

## Properties

| Property                                    | Modifiers | Type                                                                                      | Description                                                                                                        |
| ------------------------------------------- | --------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [js?](/api/rspeedy/rspeedy.sourcemap.js.md) |           | Rspack.DevTool \| undefined \| \`$\{Exclude\<Rspack.DevTool, false \| 'eval'>}-debugids\` | _(Optional)_ How the source map should be generated. Setting it to <code>false</code> will disable the source map. |



---
url: /api/rspeedy/rspeedy.tools.bundlerchain.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [bundlerChain](/api/rspeedy/rspeedy.tools.bundlerchain.md)

## Tools.bundlerChain property

The [Tools.bundlerChain](/api/rspeedy/rspeedy.tools.bundlerchain.md) changes the options of [Rspack](https://www.rspack.dev) using [rspack-chain](https://github.com/rspack-contrib/rspack-chain)<!-- -->.

**Signature:**

```typescript
bundlerChain?: ToolsConfig['bundlerChain'] | undefined;
```

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    bundlerChain(chain) {
      chain.resolve.fullySpecified(true)
    },
  },
})
```

See [rspack-chain](https://github.com/rspack-contrib/rspack-chain) for details.



---
url: /api/rspeedy/rspeedy.tools.cssextract.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [cssExtract](/api/rspeedy/rspeedy.tools.cssextract.md)

## Tools.cssExtract property

The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin)

**Signature:**

```typescript
cssExtract?: CssExtract | undefined;
```



---
url: /api/rspeedy/rspeedy.tools.cssloader.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [cssLoader](/api/rspeedy/rspeedy.tools.cssloader.md)

## Tools.cssLoader property

The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.

**Signature:**

```typescript
cssLoader?: CssLoader | undefined;
```

## Remarks

The default option is as follow:

```js
const defaultOptions = {
  modules: {
    auto: true,
    namedExport: false,
    exportLocalsConvention: 'camelCase',
    localIdentName: output.cssModules.localIdentName,
  },
  sourceMap: output.sourceMap,
  // importLoaders is `1` when compiling css files, and is `2` when compiling sass/less files
  importLoaders: 1 || 2,
};
```



---
url: /api/rspeedy/rspeedy.tools.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md)

## Tools interface

The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.

**Signature:**

```typescript
export interface Tools 
```

## Properties

| Property                                                    | Modifiers | Type                                                                                            | Description                                                                                                                                                                                                             |
| ----------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [bundlerChain?](/api/rspeedy/rspeedy.tools.bundlerchain.md) |           | ToolsConfig\['bundlerChain'] \| undefined                                                       | _(Optional)_ The [Tools.bundlerChain](/api/rspeedy/rspeedy.tools.bundlerchain.md) changes the options of [Rspack](https://www.rspack.dev) using [rspack-chain](https://github.com/rspack-contrib/rspack-chain)<!-- -->. |
| [cssExtract?](/api/rspeedy/rspeedy.tools.cssextract.md)     |           | [CssExtract](/api/rspeedy/rspeedy.cssextract.md) \| undefined                                   | _(Optional)_ The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin)                                     |
| [cssLoader?](/api/rspeedy/rspeedy.tools.cssloader.md)       |           | [CssLoader](/api/rspeedy/rspeedy.cssloader.md) \| undefined                                     | _(Optional)_ The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.                                                            |
| [rsdoctor?](/api/rspeedy/rspeedy.tools.rsdoctor.md)         |           | [RsdoctorRspackPluginOptions](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md) \| undefined | _(Optional)_ The [Tools.rsdoctor](/api/rspeedy/rspeedy.tools.rsdoctor.md) controls the options of [Rsdoctor](https://rsdoctor.dev/)<!-- -->.                                                                            |
| [rspack?](/api/rspeedy/rspeedy.tools.rspack.md)             |           | ToolsConfig\['rspack'] \| undefined                                                             | _(Optional)_ The [Tools.rspack](/api/rspeedy/rspeedy.tools.rspack.md) controls the options of [Rspack](https://www.rspack.dev/)<!-- -->.                                                                                |
| [swc?](/api/rspeedy/rspeedy.tools.swc.md)                   |           | ToolsConfig\['swc'] \| undefined                                                                | _(Optional)_ The [Tools.swc](/api/rspeedy/rspeedy.tools.swc.md) controls the options of [builtin:swc-loader](https://rspack.dev/guide/features/builtin-swc-loader)<!-- -->.                                             |



---
url: /api/rspeedy/rspeedy.tools.rsdoctor.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [rsdoctor](/api/rspeedy/rspeedy.tools.rsdoctor.md)

## Tools.rsdoctor property

The [Tools.rsdoctor](/api/rspeedy/rspeedy.tools.rsdoctor.md) controls the options of [Rsdoctor](https://rsdoctor.dev/)<!-- -->.

**Signature:**

```typescript
rsdoctor?: RsdoctorRspackPluginOptions | undefined;
```

## Example

- Use the built-in Rsdoctor.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rsdoctor: {
      disableClientServer: true,
    },
  },
})
```

See [Rsdoctor - Configuration](https://rsdoctor.dev/config/options/options) for details.



---
url: /api/rspeedy/rspeedy.tools.rspack.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [rspack](/api/rspeedy/rspeedy.tools.rspack.md)

## Tools.rspack property

The [Tools.rspack](/api/rspeedy/rspeedy.tools.rspack.md) controls the options of [Rspack](https://www.rspack.dev/)<!-- -->.

**Signature:**

```typescript
rspack?: ToolsConfig['rspack'] | undefined;
```

## Example 1

- Use object config

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack: {
      resolve: {
        fullySpecified: true,
      },
    },
  },
})
```

See [Rspack - Configuration](https://www.rspack.dev/config/index) for details.

## Example 2

- Use function with `env` utils

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack(config, { env }) {
      if (env === 'development') {
        config.devtool = 'cheap-source-map'
      }
      return config
    },
  },
})
```

See [Rsbuild - tools.rspack](https://rsbuild.dev/config/tools/rspack#env) for details.

## Example 3

- Use function with `mergeConfig` utils

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack(config, { mergeConfig }) {
      return mergeConfig(config, {
        resolve: {
          fullySpecified: true,
        },
      })
    },
  },
})
```

See [Rsbuild - tools.rspack](https://rsbuild.dev/config/tools/rspack#mergeconfig) for details.

## Example 4

- Use function with `appendPlugins` utils

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack(config, { appendPlugins, rspack }) {
      appendPlugins(new rspack.BannerPlugin({ banner: 'Hello, World!' }))
      return config
    },
  },
})
```

See [Rsbuild - tools.rspack](https://rsbuild.dev/config/tools/rspack#appendplugins) for details.



---
url: /api/rspeedy/rspeedy.tools.swc.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [swc](/api/rspeedy/rspeedy.tools.swc.md)

## Tools.swc property

The [Tools.swc](/api/rspeedy/rspeedy.tools.swc.md) controls the options of [builtin:swc-loader](https://rspack.dev/guide/features/builtin-swc-loader)<!-- -->.

**Signature:**

```typescript
swc?: ToolsConfig['swc'] | undefined;
```



---
url: /api/rspeedy/rspeedy.transformimport.cameltodashcomponentname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [camelToDashComponentName](/api/rspeedy/rspeedy.transformimport.cameltodashcomponentname.md)

## TransformImport.camelToDashComponentName property

Whether to convert camelCase imports to kebab-case.

**Signature:**

```typescript
camelToDashComponentName?: boolean | undefined;
```

## Example

- Input:

```js
import { ButtonGroup } from 'foo'
```

- Output:

When set to `true`<!-- -->:

```js
import ButtonGroup from 'foo/button-group'
```

When set to `false` or `undefined`<!-- -->:

```js
import ButtonGroup from 'foo/ButtonGroup'
```



---
url: /api/rspeedy/rspeedy.transformimport.customname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [customName](/api/rspeedy/rspeedy.transformimport.customname.md)

## TransformImport.customName property

Customize the transformed path.

**Signature:**

```typescript
customName?: string | undefined;
```

## Remarks

You you can specify the format of the transformed path. For example, by setting it to `my-lib/{{ camelCase member }}`<!-- -->, you can convert the member into camelCase.

The following formats are supported:

- `kebabCase`<!-- -->: lowercase letters, words joined by hyphens. For example: `my-variable-name`<!-- -->.

- `snakeCase`<!-- -->: lowercase letters, words joined by underscores. For example: `my_variable_name`<!-- -->.

- `camelCase`<!-- -->: first letter lowercase, the first letter of each following word uppercase. For example: `myVariableName`<!-- -->.

- `upperCase`<!-- -->: uppercase letters, other characters unchanged. For example: `MY-VARIABLE-NAME`<!-- -->.

- `lowerCase`<!-- -->: lowercase letters, other characters unchanged. For example: `my-variable-name`<!-- -->.



---
url: /api/rspeedy/rspeedy.transformimport.librarydirectory.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [libraryDirectory](/api/rspeedy/rspeedy.transformimport.librarydirectory.md)

## TransformImport.libraryDirectory property

Used to splice the transformed path, the splicing rule is `${libraryName}/${libraryDirectory}/${member}`<!-- -->, where member is the imported member.

**Signature:**

```typescript
libraryDirectory?: string | undefined;
```

## Remarks

The default value is `'lib'`<!-- -->.

## Example

- Input:

```js
import { Button } from 'foo'
```

- Output:

```js
import Button from 'foo/lib/button'
```



---
url: /api/rspeedy/rspeedy.transformimport.libraryname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [libraryName](/api/rspeedy/rspeedy.transformimport.libraryname.md)

## TransformImport.libraryName property

The original import path that needs to be transformed.

**Signature:**

```typescript
libraryName: string;
```

## Remarks

This option is required.



---
url: /api/rspeedy/rspeedy.transformimport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md)

## TransformImport interface

The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->.

**Signature:**

```typescript
export interface TransformImport 
```

## Properties

| Property                                                                                      | Modifiers | Type                 | Description                                                                                                                                                               |
| --------------------------------------------------------------------------------------------- | --------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [camelToDashComponentName?](/api/rspeedy/rspeedy.transformimport.cameltodashcomponentname.md) |           | boolean \| undefined | _(Optional)_ Whether to convert camelCase imports to kebab-case.                                                                                                          |
| [customName?](/api/rspeedy/rspeedy.transformimport.customname.md)                             |           | string \| undefined  | _(Optional)_ Customize the transformed path.                                                                                                                              |
| [libraryDirectory?](/api/rspeedy/rspeedy.transformimport.librarydirectory.md)                 |           | string \| undefined  | _(Optional)_ Used to splice the transformed path, the splicing rule is <code>$\{libraryName}/$\{libraryDirectory}/$\{member}</code>, where member is the imported member. |
| [libraryName](/api/rspeedy/rspeedy.transformimport.libraryname.md)                            |           | string               | The original import path that needs to be transformed.                                                                                                                    |
| [transformToDefaultImport?](/api/rspeedy/rspeedy.transformimport.transformtodefaultimport.md) |           | boolean \| undefined | _(Optional)_ Whether to convert import statements to default imports.                                                                                                     |



---
url: /api/rspeedy/rspeedy.transformimport.transformtodefaultimport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [transformToDefaultImport](/api/rspeedy/rspeedy.transformimport.transformtodefaultimport.md)

## TransformImport.transformToDefaultImport property

Whether to convert import statements to default imports.

**Signature:**

```typescript
transformToDefaultImport?: boolean | undefined;
```

## Example

- Input:

```js
import { Button } from 'foo'
```

- Output:

When set to `true`<!-- -->:

```js
import Button from 'foo/button'
```

When set to `false` or `undefined`<!-- -->:

```js
import { Button } from 'foo/button'
```



---
url: /api/rspeedy/rspeedy.version.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [version](/api/rspeedy/rspeedy.version.md)

## version variable

**Signature:**

```typescript
version: string
```



---
url: /api/status.md
---

<div className="rp-not-doc overflow-hidden" style={{ height: 'calc(100vh - 56px)' }}>
  <APIStatusLayout />
</div>



---
url: /blog/index.md
---

# Lynx Blog

Where the Lynx team post release notes and official announcements here. You can also follow [@lynxjs\_org](https://x.com/lynxjs_org) on X, but you won't miss anything if you only read this blog.

[Lynx 3.6: Lynx for AI, reactlynx-use, CSS for Design EngineeringJanuary 30, 2026Lynx 3.6 is now officially released! This release introduces Lynx for AI to enhance AI-native development capabilities, introduces reactlynx-use for improved developer experience, and enhances CSS capabilities for design expressiveness. On the native side, Lynx 3.6 improves platform integration with standalone BackgroundRuntime and asynchronous TemplateBundle creation on HarmonyOS, along with Auto Layout support for LynxView on iOS.

![](https://github.com/loongliu.png)Leron LiuPerformance Lead @ Lynx![](https://github.com/Dugyu.png)Guangyu DuDesign Engineering @ Lynx![](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org](/next/blog/lynx-3-6)[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)[Announcing Lynx for HarmonyOSSeptember 25, 2025Today, we are happy to share that Lynx now provides public beta support for HarmonyOS, delivering feature parity in CSS, Elements, and APIs — along with the same level of native performance and user experience.

![](https://github.com/rel-q.png)Qiang BaiSoftware Engineer![](https://github.com/toretto-wt.png)Wentao ShiRendering Lead @ Lynx![](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org](/next/blog/lynx-harmony)[Lynx 3.4: HarmonyOS Support, Trace and Recorder, Text Input ElementsSeptember 3, 2025

![](https://github.com/loongliu.png)Leron LiuPerformance Lead @ Lynx![](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org](/next/blog/lynx-3-4)[What’s new in Lynx 3.2May 14, 2025

![](https://github.com/toretto-wt.png)Wentao ShiRendering Lead @ Lynx![](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org](/next/blog/lynx-3-2)[Lynx Roadmap 2025March 19, 2025Two weeks ago, we launched Lynx as an open-source project and have since gathered valuable insights and feedback from the community. Thank you for engaging with Lynx, even as we take our first steps as a new member of the open-source cross-platform ecosystem. Today, I'm pleased to share the 2025 roadmap of Lynx.

![](https://github.com/lynx-family.png)Shouqun LiuEngineering Manager @ Lynx](/next/blog/lynx-open-source-roadmap-2025)[Lynx: Unlock Native for MoreMarch 5, 2025Today, we're excited to introduce Lynx, a family of technologies empowering developers to use their existing web skills to create truly native UIs for both mobile and web from a single codebase...

![](https://github.com/huxpro.png)Xuan HuangArchitect @ Lynx![](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org](/next/blog/lynx-unlock-native-for-more)


---
url: /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(
          {
            query: true,
            id: true,
          },
          (result) => resolve(result.map(({ query }) => query)),
        )
        .exec();
    });

    Promise.all(
      resArray.map((selectorQuery) => {
        return new Promise<{
          top: number;
          left: number;
          width: number;
          height: number;
          id: string;
        }>((resolve, reject) => {
          selectorQuery.selectRoot()
            .invoke({
              method: "boundingClientRect",
              success: resolve,
              fail: reject,
            })
            .exec();
        });
      }),
    ).then((values) => {
      textsInfo = values.map(({ top, left, width, height, id }) => ({
        id,
        left,
        top,
        width,
        height,
        startX: -1,
        startY: 0,
        endX: width,
        endY: height,
      }));
    });
  }

  // Function to execute text selection on a specific node
  function execSelection(
    node: TextNodeInfo,
    startX: number,
    startY: number,
    endX: number,
    endY: number,
    showStartHandle = true,
    showEndHandle = true,
  ) {
    lynx
      .createSelectorQuery()
      .select(`#${node.id}`)
      .invoke({
        method: "setTextSelection",
        params: {
          startX,
          startY,
          endX,
          endY,
          showStartHandle,
          showEndHandle,
        },
        success(res) {
          if (!res) {
            return;
          }
          const boxes = res.boxes || [];
          const hs = res.handles || [];
          if (Array.isArray(boxes) && boxes.length > 0) {
            node.startX = boxes[0].left;
            node.startY = boxes[0].top + boxes[0].height / 2;
            node.endX = boxes[boxes.length - 1].left + boxes[boxes.length - 1].width;
            node.endY = boxes[boxes.length - 1].top + boxes[boxes.length - 1].height / 2;
          } else {
            node.startX =
              node.startY =
              node.endX =
              node.endY =
                -1;
          }
          showStartHandle && (handlers[0] = { ...hs[0], startX: node.startX, startY: node.startY });
          showEndHandle && (handlers[1] = { ...hs[1], startX: node.endX, startY: node.endY });
        },
      })
      .exec();
    if (startX === -1) {
      node.startX = -1;
      handlers = [];
    }
  }

  // Function to set the text selection based on the start and end coordinates
  function setSelection(x1: number, y1: number, x2: number, y2: number) {
    const [[startX, startY], [endX, endY]] = [
      [x1, y1],
      [x2, y2],
    ].sort((a, b) => {
      if (a[1] === b[1]) {
        return a[0] - b[0];
      }
      return a[1] - b[1];
    });
    const clear: TextNodeInfo[] = [];
    const update: TextNodeInfo[] = [];
    for (const node of textsInfo) {
      if (
        (startY < node.top && node.top + node.height < endY)
        || (node.left <= startX && startX <= node.left + node.width && node.top <= startY
          && startY <= node.top + node.height)
        || (node.left <= endX && endX <= node.left + node.width && node.top <= endY && endY <= node.top + node.height)
      ) {
        update.push(node);
      } else if (node.startX !== -1) {
        clear.push(node);
      }
    }
    if (clear.length > 0 || update.length > 0) {
      for (const node of clear) {
        execSelection(node, -1, -1, -1, -1, false, false);
      }
      const start = update[0];
      const end = update[update.length - 1];
      if (update.length === 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          Math.min(start.width, endX - start.left),
          Math.min(start.height, endY - start.top),
          true,
          true,
        );
      } else if (update.length > 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          start.width,
          start.height,
          true,
          false,
        );
        for (let i = 1; i < update.length - 1; i++) {
          execSelection(update[i], 0, 0, update[i].width, update[i].height, false, false);
        }
        execSelection(
          end,
          0,
          0,
          Math.min(end.width, endX - end.left),
          Math.min(end.height, endY - end.top),
          false,
          true,
        );
      }
      return true;
    }
    return false;
  }

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view
          id="container"
          style={{ width: "90vw" }}
          className="Container"
          bindlongpress={handleLongPress}
          bindtouchstart={handleTouchStart}
          bindtouchmove={handleTouchMove}
          bindtouchend={handleTouchEnd}
          bindtap={handleTap}
        >
          <text id="0" text-selection={true} custom-text-selection={true} flatten={false} className="Title">
            This is title
          </text>
          <view className="SplitLine" />
          <text id="1" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            1.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="2" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            2.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="3" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            3.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
        </view>
      </view>
    </page>
  );
};

export default CrossTextSelection;

root.render(<CrossTextSelection />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Microtasks <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._



---
url: /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` | Web: `dist/base.web.bundle`

```tsx {13-21}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "20px" }}>
      <view style={{ width: "100%", padding: "10px", backgroundColor: "#87654321", borderRadius: "10px" }}>
        <textarea
          style={{ width: "100%", color: "blue", fontSize: "50px" }}
          placeholder="Title"
          maxlines={2}
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>

      <view
        style={{
          width: "100%",
          padding: "10px",
          marginTop: "20px",
          backgroundColor: "#12345678",
          borderRadius: "10px",
        }}
      >
        {
          <textarea
            style={{ width: "100%", height: "300px", fontSize: "30px" }}
            placeholder="Content"
            bindinput={(res: any) => {
              console.log(res.detail.value);
              setInputContent(res.detail.value);
            }}
          />
        }
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## List Recycle Optimization

Lynx 3.4 optimizes the recycling strategy of the `<list>` element to improve rendering performance.

### Recycle `<list>` Sticky Item

When a `<list-item>` is scrolled out of the `<list>` viewport, the original recycling mechanism would cache the item for reuse. Prior to Lynx 3.4, `<list-item>` elements with the sticky attribute were not recycled. In long lists making heavy use of the sticky feature, this could lead to high memory usage. Lynx 3.4 optimizes this strategy; sticky items are now also recycled after scrolling out of the viewport.
If this change adversely affects your existing scenarios, you can temporarily disable this optimization by setting [`experimental-recycle-sticky-item={false}`](/api/elements/built-in/list.md#experimental-recycle-sticky-item). If you encounter any issues, please provide feedback via an issue.

<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.



---
url: /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" />



---
url: /blog/lynx-3-6.md
---

_January 30th, 2026_

# Lynx 3.6: Lynx for AI, reactlynx-use, CSS for Design Engineering

<BlogAvatar list={['liujilong', 'Dugyu', 'lynx']} />

Lynx 3.6 is now officially released!

This release introduces Lynx for AI to enhance AI-native development capabilities, introduces `reactlynx-use` for improved developer experience, and enhances CSS capabilities for design expressiveness.

On the native side, Lynx 3.6 improves platform integration with standalone `BackgroundRuntime` and asynchronous `TemplateBundle` creation on HarmonyOS, along with Auto Layout support for LynxView on iOS.

Let's take a closer look at what's new in Lynx 3.6.

## Lynx for AI: `AGENTS.md` and MCPs

AI assistants are quickly becoming part of everyday development. With Lynx 3.6, we’re introducing **Lynx for AI**—a new section on our website at [/ai](/ai.md) to help coding agents understand Lynx, follow best practices, and help you ship.

In this release, we’re shipping [`AGENTS.md`](/ai/agentsmd.md) and two MCP servers as the first building blocks for agent-friendly Lynx projects (Skills coming soon!).

### Lynx Docs MCP

[Lynx Docs MCP](/ai/lynx-docs-mcp.md) connects your coding agent (Gemini, Claude, Cursor, Copilot, etc.) to Lynx documentation via MCP, using [llms.txt](https://lynxjs.org/llms.txt) plus carefully designed prompts so the agent can retrieve the right docs and act on them.

### Lynx DevTool MCP

[Lynx DevTool MCP](/ai/lynx-devtool-mcp.md) helps coding agents connect to devices and inspect/control Lynx pages like DevTools: read elements/console/source code, perform interactions such as clicks and drags, and capture screenshots for multimodal analysis.

## `reactlynx-use`: Hooks for ReactLynx

[`reactlynx-use`](https://lynx-community.github.io/reactlynx-use) is a hooks toolkit for ReactLynx projects.

It combines two sets of hooks: community-proven utilities that follow standard React patterns (such as `useEffectOnce`, `useDebounce`, etc.), built upon the excellent foundation provided by [react-use](https://github.com/streamich/react-use), and Lynx-specific hooks that expose Lynx capabilities and its dual-thread model through a React-friendly API.

Notable Lynx-specific hooks include:

- **useVelocity**: Track the velocity and direction of tap events on the main thread.
- **useTapLock**: Constrain main-thread tap interactions to a specific direction or range.
- **useMainThreadImperativeHandle**: A main-thread counterpart of `useImperativeHandle`.
- **useEventListener**: A flexible event subscription hook supporting `exposure`, `disexposure`, and more.

This keeps everyday logic in familiar hooks, while making it straightforward to tap into Lynx’s main-thread input model and runtime events when you need to.

![reactlynx-use](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/reactlynx-use.jpeg)

## CSS for Design Engineering

From Lynx 3.6 onward, CSS takes on a more explicit role in design engineering and design systems.
As a medium for expressing design intent, CSS describes how decisions are scoped and composed, and how visual structure and perception are formed in the interface.

This release focuses on improving CSS expressiveness through **CSS variables**, **gradients**, and **filters**.

For each capability, we’ve also prepared a polished demo that you can render and interact with on the web.

### Inline CSS Variables for Computable Styling

As of Lynx 3.6, [CSS variables](/api/css/properties/css-variable.md) can be defined and referenced inline. This allows them to be applied directly at component boundaries (where JS-defined parameters are handed off to CSS), without relying on ancestor class switches (such as `theme-light` / `theme-dark`) or imperative JS `setProperty` calls.

It becomes essential when a component's style is user-selected or computed at runtime, since such continuous values cannot be represented by a finite set of predefined classes and would otherwise require imperative style updates.

```tsx
style={{
  '--x': pointer.x,  // normalized parameter from JS
  backgroundColor: 'var(--dot-accent-color)', //defer resolution to component CSS
}}
```

Inline CSS variables provide a direct path for passing design parameters from JS into CSS's inheritance and computation model, so that design intent can be dynamically expressed and resolved while preserving component-level scoping and the declarative styling model.

**This is an example below:  design-guide**

**Entry:** `src/force_field`
**Bundle:** `dist/force_field.lynx.bundle` | Web: `dist/force_field.web.bundle`

```tsx
import type { DotFieldProps, DotProps } from "./field.types.js";
import "./field.css";

/**
 * Dot consumes normalized, unitless params.
 * Positioning and sizing are resolved via field-scoped CSS vars.
 */
function Dot({ x = 0, y = 0, s = 1, color, useAccent }: DotProps) {
  return (
    <view
      className="dot"
      /**
       * Inline CSS variables:
       * route accent color to a field-scoped CSS token
       * (`--dot-accent-color`), rather than computing it in JS
       */
      style={`--x:${x}; --y:${y}; --s:${s}; background-color:${useAccent ? "var(--dot-accent-color)" : color}`}
    />
  );
}

/**
 * DotField defines the styling boundary for a dot-based field.
 * Default field-level tokens (e.g. `--field-size`, `--dot-size`) live in CSS;
 * JS only injects token overrides when provided.
 */
function DotField({
  fieldSize,
  dotSize,
  dotColor,
  dotAccentColor,
  style,
  children,
  ...rest // Interaction Handlers
}: DotFieldProps) {
  const styleParts: string[] = [];

  // Token overrides: only write when the caller provides a value.
  if (fieldSize != null) styleParts.push(`--field-size:${fieldSize}px`);
  if (dotSize != null) styleParts.push(`--dot-size:${dotSize}px`);
  if (dotColor) styleParts.push(`--dot-color:${dotColor}`);
  if (dotAccentColor) styleParts.push(`--dot-accent-color:${dotAccentColor}`);

  const mergedStyle = style
    ? `${styleParts.join("; ")}; ${style}`
    : styleParts.join("; ");

  return (
    <view
      style={mergedStyle}
      className="dot-field"
      {...rest}
    >
      {children}
    </view>
  );
}

export { Dot, DotField };

```



### Nested CSS Variables for Token Layering

With Lynx 3.6, [CSS variables](/api/css/properties/css-variable.md) can be defined in terms of other variables, allowing [design tokens](https://m3.material.io/foundations/design-tokens/overview) to be layered and resolved compositionally.

Design tokens capture high-level design decisions, such as colors, typography, spacing, shadows, and glows. Nested CSS variables enable these tokens to flow down into component-level variables and concrete visual styles.

```css
/* Resolve and compose shadow tokens via nested CSS variables. */
.card {
  --blur: 12px;
  --ambient-shadow: 0 0 var(--blur) var(--color);
  box-shadow: var(--ambient-shadow), var(--rim-shadow);
}
```

This is especially important for composite declarations like `box-shadow`. A single `box-shadow` may contain multiple shadow layers, each combining several interacting dimensions such as offset, blur, spread, and color.
With nested CSS variables, shadow layers can now be derived, combined, and adjusted from design tokens, while keeping their structure explicit and traceable in CSS.

**This is an example below:  design-guide**

**Entry:** `src/soft_glow`
**Bundle:** `dist/soft_glow.lynx.bundle` | Web: `dist/soft_glow.web.bundle`

```css
/* Semantic shadow tokens are progressively resolved into
 * ambient and rim shadows through nested CSS variables,
 * allowing visual intensity to be adjusted without changing structure.
 */
.card {
  --primary: 254, 105, 161;
  --secondary: 255, 115, 133;
  --accent: 169, 152, 191;

  --color: rgba(var(--secondary), 0.65);
  --rim-color: rgba(var(--primary), 0.9);

  --blur: 3px;
  --spread: 0;
  --rim-blur: 2px;
  --rim-spread: -1px;

  --ambient-shadow: 0 0 var(--blur) var(--spread) var(--color);
  --rim-shadow: 0 0 var(--rim-blur) var(--rim-spread) var(--rim-color);
  border-radius: 24px;
  box-shadow:
    var(--ambient-shadow),
    var(--rim-shadow);
  width: 84px;
  height: 84px;
  background: linear-gradient(
    rgb(var(--accent)),
    rgb(var(--primary))
  );
}

/* Elevation levels adjust shadow parameters
 * while preserving the same compositional structure.
 */
.ele-1 {
  --blur: 3px;
  --spread: 0;
  --rim-blur: 2px;
  --rim-spread: -1px;
}

.ele-2 {
  --blur: 10px;
  --spread: -1px;
  --rim-blur: 6px;
  --rim-spread: -2px;
}

.ele-3 {
  --blur: 24px;
  --spread: -3px;
  --rim-blur: 12px;
  --rim-spread: -4px;
}

.ele-4 {
  --blur: 44px;
  --spread: -5px;
  --rim-blur: 24px;
  --rim-spread: -8px;
}

/* =========================
 * Layout
 * ========================= */

.design-container {
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: #0d0d0d;
  gap: 36px;
}

.canvas {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  gap: 24px;
}

```



### Conic Gradients as Design Primitives

Lynx 3.6 adds support for the [`conic-gradient()`](/api/css/data-type/gradient.md) CSS image function. You can use it in CSS properties that accept `<image>` values, such as in `background-image` and `mask-image`, to create continuous angular color transitions directly in CSS.

```css
.bg {
  background-image: conic-gradient(from 30deg, #ff7385, #fe69a1, #00d0f1);
}
```

Conic gradients are a natural fit for angular or cyclic representations, including color wheels and hue pickers. In practice, they’re a lightweight design primitive you can compose into interactive controls and visual tools.

**This is an example below:  design-guide**

**Entry:** `src/color_wheels`
**Bundle:** `dist/color_wheels.lynx.bundle` | Web: `dist/color_wheels.web.bundle`

```css
.gradient-disc {
  background-image: conic-gradient(#ff7385, #fe69a1, #a998bf, #00d0f1);
}

.gradient-ring {
  background-image: conic-gradient(#ff7385, #fe69a1, #a998bf, #00d0f1, #ff7385);
}

.gradient-offset {
  background-image: conic-gradient(
    from 36deg at 33% 67%,
    #ff7385,
    #fe69a1,
    #00d0f1
  );
}

.wheel {
  width: 120px;
  height: 120px;
  border-radius: 9999px;
  display: flex;
  justify-content: center;
  align-items: center;

  position: relative;
}

.wheel-hole {
  width: 96px;
  height: 96px;
  border-radius: 9999px;
  background-color: #0d0d0d;
}

.wheel-picker {
  position: absolute;

  width: 16px;
  height: 16px;
  border-radius: 9999px;

  background-color: #ffffff;

  box-shadow:
    0 0 0 2px rgba(255, 255, 255, 0.25),
    0 4px 12px rgba(0, 0, 0, 0.4);

  top: 50%;
  left: 50%;

  /* 
   * Step 1: move picker's center onto the wheel center
   * Step 2: rotate to angle
   * Step 3: translate outwards by radius
   */
  transform: rotate(30deg) translateX(46px);
  transform-origin: 0 0;
}

/* =========================
 * Layout
 * ========================= */

.design-container {
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: #0d0d0d;
  gap: 24px;
}

```



### CSS Filters for Shape Formation

Lynx 3.6 extends CSS filter support with `contrast`, `brightness`, and `saturate`.

With these additions, the CSS [`filter`](/api/css/properties/filter.md) property becomes a composable tool for shape formation.
The newly supported `contrast` filter, when combined with the existing `blur` capability, amplifies overlapping regions and allows soft shapes to merge into coherent forms.

Visual structures such as merging, perceptual grouping, and fluid boundaries can be constructed directly in CSS, without relying on bitmap assets or custom rendering pipelines.

**This is an example below:  design-guide**

**Entry:** `src/gooey_effect`
**Bundle:** `dist/gooey_effect.lynx.bundle` | Web: `dist/gooey_effect.web.bundle`

```css
/*
 * Gooey Effect (blur + contrast)
 *
 * Visual output depends on each platform’s graphics pipeline:
 * - Web renders a precise, crisp Gaussian blur.
 * - iOS appears softer and more diffused.
 * - Android may exhibit minor geometric artifacts on small surfaces
 *   (e.g. a diamond-shaped silhouette) due to blur and downsampling.
 *
 * Blur is applied at the container level to reduce per-element artifacts.
 */

.stage {
  filter: contrast(5);
  /* Background color must be explicit for contrast-based thresholding */
  background-color: black;
  width: 100%;
  height: 200px;
}

.dots-container {
  /* Apply blur at the group level to reduce per-element blur artifacts on some platforms */
  filter: blur(12px);
  width: 100%;
  height: 100%;
  display: flex;
  justify-content: center;
  align-items: center;
  gap: 4px;
}

.dot {
  /* Keep dots crisp; container-level blur produces the gooey merge */
  width: 54px;
  height: 54px;
  border-radius: 999px;
  background: white;
  animation: blob 2200ms ease-in-out infinite;
}

/* Stagger phases without nth-child */
.g1 {
  animation-delay: 0ms;
}
.g2 {
  animation-delay: -350ms;
}
.g3 {
  animation-delay: -700ms;
}
.g4 {
  animation-delay: -1050ms;
}

@keyframes blob {
  0% {
    transform: translateX(-18px) translateY(0px) scale(1.00);
  }
  25% {
    transform: translateX(7.5px) translateY(-4.5px) scale(1.06);
  }
  50% {
    transform: translateX(21px) translateY(0px) scale(1.00);
  }
  75% {
    transform: translateX(4.5px) translateY(4.5px) scale(0.98);
  }
  100% {
    transform: translateX(-18px) translateY(0px) scale(1.00);
  }
}

/* =========================
 * Layout
 * ========================= */

.design-container {
  min-width: 300px;
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: black;
  gap: 40px;

  padding-left: 0;
  padding-right: 0;
}

```



## Native APIs

### Standalone BackgroundRuntime on HarmonyOS

HarmonyOS now supports standalone [BackgroundRuntime](/api/lynx-native-api/lynx-background-runtime.md), aligning more closely with existing Android and iOS capabilities.

With standalone BackgroundRuntime, developers can run JavaScript tasks independently of rendering, or pre-create background runtimes to reduce LynxView initialization latency.

### Asynchronous TemplateBundle Creation on HarmonyOS

On Android and iOS, [`TemplateBundle.fromTemplate`](/api/lynx-native-api/template-bundle/from-template.md) can be called from any thread. On HarmonyOS, however, ArkTS logic must run on the application's main thread.

To reduce main-thread I/O blocking, Lynx 3.6 introduces asynchronous APIs for creating `TemplateBundle` instances on HarmonyOS:

- [`TemplateBundle.fromTemplateAsync`](/api/lynx-native-api/template-bundle/from-template-async.md)
- [`TemplateBundle.fromTemplateAsyncWithOption`](/api/lynx-native-api/template-bundle/from-template-async-with-option.md)

### AutoLayout Support for LynxView on iOS

On iOS, LynxView now supports Auto Layout via [`[LynxView enableAutoLayout]`](/api/lynx-native-api/lynx-view/enable-auto-layout.md).

When enabled, LynxView can derive layout parameters directly from client-side Auto Layout constraints, eliminating the need to configure layout values manually.

## Upgrade Guide

To upgrade to Lynx 3.6, follow the [integration guide](https://lynxjs.org/3.6/guide/start/integrate-with-existing-apps.html) and update your Lynx dependency versions accordingly.
**Lynx for AI**



---
url: /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!



---
url: /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.



---
url: /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)



---
url: /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.



---
url: /ai/index.md
---

# Lynx for AI

LLMs are trained on public web data, which means they often lack awareness of the latest Lynx features and best practices. The Lynx team and community are developing a suite of tools to help LLMs understand and develop Lynx more effectively.

## Teaching LLMs about Lynx

### Using Lynx Docs MCP

[Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) is a standard for connecting LLMs to external tools. Lynx Docs MCP allows the agent fetch accurate guides, API references directly from the Lynx documentation site, to ensure its answers stay correct and up to date.

Read more about Lynx Docs MCP in [Lynx Docs MCP](/ai/lynx-docs-mcp.md).

### Using `llms.txt`

[llms.txt](https://llmstxt.org/) is a standard to help LLMs use a website as a knowledge base. The Lynx website fully supports it, so you can either copy the Markdown or provide its URL to any LLM with web-browsing. For every page, you can get the original Markdown by replacing the `.html` extension with `.md`. For example:

- [https://lynxjs.org/llms.txt](https://lynxjs.org/llms.txt)
- [https://lynxjs.org/react/introduction.md](https://lynxjs.org/react/introduction.md)

## Developing with Agents

### Using `AGENTS.md`

The [`AGENTS.md`](https://agents.md) file is similar to `README.md`, but it's for agents. Learn how to add a suitable `AGENTS.md` for your Lynx project in [AGENTS.md for Lynx](/ai/agentsmd.md).

### Lynx DevTool MCP

[Lynx DevTool MCP](/ai/lynx-devtool-mcp.md) is the Lynx DevTool for coding agents.
It lets coding agents _**control, operate and preview**_ Lynx pages, just like human does in DevTool.

Read more in [Lynx DevTool MCP](/ai/lynx-devtool-mcp.md).



---
url: /ai/lynx-devtool-mcp.md
---

# Lynx DevTool MCP

Lynx DevTool MCP is a [Model Context Protocol (MCP) server](https://modelcontextprotocol.io/docs/learn/server-concepts) that lets coding agents _**control, operate and preview**_ Lynx pages.

## Get started

Add the following config to your MCP client:

```json
{
  "mcpServers": {
    "lynx-devtool": {
      "command": "npx",
      "args": ["-y", "@lynx-js/devtool-mcp-server@latest"]
    }
  }
}
```

<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.



---
url: /ai/lynx-docs-mcp.md
---

# Lynx Docs MCP

`@lynx-js/docs-mcp-server` is an MCP server providing docs for LLMs from [Lynx official site](https://lynxjs.org/), with carefully designed prompting. It lets your coding agent (such as Gemini, Claude, Cursor or Copilot) access Lynx documentation to assist you in development tasks. Therefore, we have specifically optimized [llms.txt](https://lynxjs.org/llms.txt), a condensed version of the documentation site optimized for LLMs.

## Requirements

- [Node.js](https://nodejs.org/) v18.17 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.

## Getting started

Add the following config to your MCP client:

```json
{
  "mcpServers": {
    "lynx-docs": {
      "command": "npx",
      "args": ["-y", "@lynx-js/docs-mcp-server@latest"]
    }
  }
}
```

`@lynx-js/docs-mcp-server` works best with MCP clients that supports [Server Instructions](https://modelcontextprotocol.io/specification/draft/schema#initializeresult), such as Claude Code.
If you find your MCP client doesn't know about the MCP server,
you can manually provide the following instructions
(e.g. in your `AGENTS.md`, `CLAUDE.md`, or just send it along with your question):

```md
For any questions or requirements regarding Lynx:

1. Use the "List Resources Tool" to list all Resources provided in MCP "lynx-docs".
2. First read MCP Resources "lynx-docs://llms.txt" (**REQUIRED**), this document is an ENTRYPOINT of all Lynx Docs.
3. After reading "lynx-docs://llms.txt", use the "Read MCP Resources Tool" to retrieve docs you need based on the user's questions or requirements, please read them proactively.
4. If available, prioritize obtaining Lynx-related information through MCP Resources tools over external web searches.
```

<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.



---
url: /help/api.md
---

# Documenting APIs

The Lynx documentation relies on a structured system to ensure API references are accurate and consistent.

## Compatibility Data (`lynx-compat-data`)

The source of truth for platform compatibility is stored in `packages/lynx-compat-data`. This is a JSON database similar to MDN's browser-compat-data.

### Adding a New API

1. Navigate to `packages/lynx-compat-data`.
2. Find the appropriate JSON file (e.g., `lynx-api/global/console/log.json`).
3. Add your API definition following the schema.

## Displaying API Tables

To display a compatibility table in your documentation, use the `<APITable>` component.

### Using Frontmatter (Recommended)

It is recommended to define the `api` field in the frontmatter.

```yaml
---
api: lynx-api/global/console/log
---
```

Then place `<APITable />` in your MDX file. It will automatically read the `api` field.

```tsx
<APITable />
```

### Multiple Tables (Explicit Query)

When you need to display multiple tables on a single page, you can pass the `query` prop explicitly.

For example, in [fetch](/api/lynx-api/global/fetch.md), separate tables are used for `Headers`, `Request`, and `Response`:

```tsx
### Headers

<APITable query="lynx-api/fetch/Headers" />

### Request

<APITable query="lynx-api/fetch/Request" />
```

**Compatibility Table**
**Query:** `lynx-api.fetch.Headers`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Headers](https://developer.mozilla.org/docs/Web/API/Headers)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| 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.



---
url: /help/blog.md
---

# Writing Blog Posts

The Lynx website hosts a blog to share updates, tutorials, and announcements.

## Location

All blog posts are located in `docs/en/blog/`.

## Creating a New Post

1. Create a new `.mdx` file in `docs/en/blog/`. The filename will be part of the URL.
2. Add the necessary frontmatter.

```yaml
---
title: My New Blog Post
date: 2024-01-01
author: Your Name
description: A short summary of the post.
---
```

3. Write your content using standard Markdown and MDX components.

## Blog Components

We provide specialized components for blog listings and author avatars.

### `<BlogList>`

Renders the list of blog posts automatically.

```tsx
import { BlogList } from '@lynx';

<BlogList limit={1} />;
```

[Lynx 3.6: Lynx for AI, reactlynx-use, CSS for Design EngineeringJanuary 30, 2026Lynx 3.6 is now officially released! This release introduces Lynx for AI to enhance AI-native development capabilities, introduces reactlynx-use for improved developer experience, and enhances CSS capabilities for design expressiveness. On the native side, Lynx 3.6 improves platform integration with standalone BackgroundRuntime and asynchronous TemplateBundle creation on HarmonyOS, along with Auto Layout support for LynxView on iOS.

![](https://github.com/loongliu.png)Leron LiuPerformance Lead @ Lynx![](https://github.com/Dugyu.png)Guangyu DuDesign Engineering @ Lynx![](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org](/next/blog/lynx-3-6)
### `<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.



---
url: /help/components.md
---

# MDX Components Reference

This page serves as a reference for the custom components available in the Lynx documentation. You can import these from `@lynx`.

## Callout & Alerts

Used to highlight important information. You can use standard Markdown syntax `:::type` for callouts.

```markdown
:::info
This is an info callout.
:::

:::warning
This is a warning callout.
:::

:::tip
This is a tip callout.
:::

:::danger
This is a danger callout.
:::
```

:::info
This is an info callout.
:::

:::warning
This is a warning callout.
:::

:::tip
This is a tip callout.
:::

:::danger
This is a danger callout.
:::

## Badges

### Platform Badges

Indicate platform support.

```tsx
<AndroidOnly />
<IOSOnly />
<WebOnly />
<HarmonyOnly />
```

<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" />



---
url: /help/dashboard.md
---

# API Status Dashboard Guide

:::tip
This usage guide was generated with AI assistance. If you find any inaccuracies, please help us improve it by submitting a pull request.
:::

This guide explains how to use the Lynx API Status Dashboard to explore API compatibility across different platforms.

![API Status Dashboard Overview](/api-status-help/api-status-main.png)

***

## 1. Select Platform

At the top of the dashboard, you'll find the **Platform Selector** which allows you to select one or multiple platforms to view their specific API coverage.

### Native Platforms

- **Android** - Mobile Android platform
- **iOS** - Apple iOS platform
- **Harmony** - HarmonyOS platform
- **Web** - Web Lynx implementation

Use the checkboxes to select multiple platforms simultaneously. The dashboard will update to show coverage statistics for the combined selection.

### Clay Platforms

Click the **Clay** toggle button to reveal additional Clay platform options:

![Clay Platforms Expanded](/api-status-help/api-status-clay-platforms.png)

Clay platforms include:

- **Clay (Android)** - Clay running on Android
- **Clay (iOS)** - Clay running on iOS
- **Clay (macOS)** - Clay running on macOS
- **Clay (Windows)** - Clay running on Windows

***

## 2. Search, Filter, and View APIs

### Search Box

Use the search box to quickly find specific APIs by name or description. The search is case-insensitive and matches partial text.

**Examples:**

- Search `image` to find all image-related APIs
- Search `scroll` to find scrolling functionality
- Search `animation` to find animation APIs

### Category Filter

The first dropdown allows you to filter APIs by category:

- **All** - Show all categories
- **ELEMENT** - Element-related APIs
- **CSS** - CSS property support
- **API** - JavaScript API methods

### State Filter

The second dropdown filters APIs by their support status on the selected platform:

- **All** - Show all APIs
- **Supported** - Only show supported APIs
- **Unsupported** - Only show unsupported APIs

### API List

The API list displays all matching APIs in a two-column grid layout. Each API item shows:

- **Category badge** (e.g., `ELEMENT`, `CSS`, `API`)
- **API name** (e.g., `commonality`, `image.loop-count`)
- **Color coding**:
  - 🟢 **Green background** - API is supported on all selected platforms
  - 🟡 **Yellow background** - API is partially supported (supported on some but not all selected platforms)
  - 🔴 **Red background** - API is not supported on any selected platform

For partially supported APIs, a small indicator (e.g., "2/3") shows how many of the selected platforms support that feature.

By default, only the first 100 results are shown for performance. Click **"Show All"** to display all matching results.

### API Detail Drawer

Click on any API item to open the detailed compatibility drawer:

![API Detail Drawer](/api-status-help/api-status-drawer.png)

The drawer shows a compatibility table with:

- **Rows** - Each sub-API or property
- **Columns** - All platforms (Android, iOS, HarmonyOS, macOS, Windows, Web)

| Icon           | Meaning                      |
| -------------- | ---------------------------- |
| ✓ with version | Supported since that version |
| ✗ No           | Not supported                |
| ?              | Support status unknown       |

Click the **"View source"** link to see the raw compatibility data in the GitHub repository.

***

## 3. View Platform Coverage and Trends

The bottom section shows platform statistics and historical trends:

![Coverage Card and Trend Chart](/api-status-help/api-status-coverage-trend.png)

### Coverage Card (Left)

- **Percentage** - Overall API coverage (e.g., 87%)
- **Fraction** - Exact count (e.g., 945 / 1,092)
- **Progress bar** - Visual representation with platform-specific color

### Trend Chart (Right)

- **X-axis** - Lynx versions (e.g., 2.14 → 3.4)
- **Y-axis** - API coverage percentage
- **Line** - Coverage progression over time

This helps you understand how API support has improved across versions.

### Category Table

The **Coverage** section provides a breakdown by API category:

![Category Table with Expanded View](/api-status-help/api-status-category-expanded.png)

| Column   | Description                             |
| -------- | --------------------------------------- |
| Category | API category name (e.g., Elements, CSS) |
| Coverage | Percentage and count of supported APIs  |
| Missing  | Number of unsupported APIs (if any)     |

**Highlight Modes:**

- **Highlight Good** (Green mode) - Emphasizes high coverage categories
- **Highlight Gap** (Red mode) - Emphasizes low coverage categories

Click on any category row to expand it and see the individual APIs. Unsupported APIs are highlighted in red for easy identification.

***

## 4. Recently Added APIs

The **Recently Added** section lists APIs that were recently added to Lynx, grouped by version.

![Recently Added APIs by Version](/api-status-help/api-status-recently-added.png)

Each version group shows:

- **Version number** (e.g., v3.5, v3.4, v2.18)
- **API count** for the selected platform
- **List of APIs** added in that version

This is useful for tracking new features in each Lynx release.

***

## Tips

1. **Start with platform selection** - Choose your target platforms (one or more) first to see relevant coverage data.
2. **Use Colorblind Mode** - Toggle the **Colorblind Mode** switch in the sidebar footer to enable a high-contrast Blue/Orange theme for better accessibility.
3. **Use search for specific APIs** - If you know the API name, search is faster than scrolling.
4. **Check the drawer for details** - The compatibility table shows version-specific information.
5. **Monitor trends** - Use the trend chart to understand coverage improvements over time.
6. **Toggle Clay for desktop** - Enable Clay platforms if you're building cross-platform desktop apps.

***

## Need Help?

If you have questions about API compatibility or need assistance:

- Check the [API documentation](/api/index.md)
- Contribute on [GitHub](https://github.com/lynx-family/lynx)



---
url: /help/example.md
---

# Managing Interactive Examples (`<Go>`)

Interactive examples allow users to preview and edit code directly in the documentation. This guide explains how to manage these examples using the dedicated workspace and the `<Go>` component.

## Overview

The interactive example system allows you to embed live, runnable Lynx code in your documentation. It consists of:

1. **Source Packages**: Examples are real npm packages managed in `packages/lynx-example-packages/`.
2. **Build Process**: A script bundles these packages into static assets for the website.
3. **`<Go>` Component**: A React component that renders the interactive editor and preview in your MDX files.

***

## 1. Using the `<Go>` Component

To embed an interactive example in your documentation, use the `<Go>` component.

### Basic Usage

Import `Go` from `@lynx` and provide the `example` ID (which corresponds to the package directory name).

```tsx
import { Go } from '@lynx';

<Go example="view" />;
```

### Component Props

| Prop               | Type     | Default          | Description                                                                                                 |
| :----------------- | :------- | :--------------- | :---------------------------------------------------------------------------------------------------------- |
| `example`          | `string` | **Required**     | The ID of the example to load (e.g., `"view"`). Matches the directory name in `docs/public/lynx-examples/`. |
| `defaultFile`      | `string` | `"package.json"` | The file path to display in the code editor initially.                                                      |
| `defaultEntryName` | `string` | -                | The specific entry point to run (if the example has multiple bundles).                                      |
| `img`              | `string` | -                | URL to a custom preview image (overrides the default `preview-image.png`).                                  |
| `highlight`        | `object` | -                | Line highlighting configuration. Format: `{ "path/to/file": "start-end" }`.                                 |
| `schema`           | `string` | -                | Custom schema URL pattern for the preview. Use `{{{url}}}` as a placeholder for the bundle URL.             |

### Advanced Example

```tsx
<Go
  example="view"
  defaultFile="src/App.tsx"
  defaultEntryName="main"
  highlight={{ 'src/App.tsx': '5-10' }}
/>
```

**This is an example below:  view**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx 5-10
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ReactElement } from "react";

const RenderExample = () => {
  return (
    <view
      style={{
        borderLeftWidth: "15px",
        borderRightWidth: "60px",
        borderTopWidth: "100px",
        borderBottomWidth: "50px",
        borderColor: "green red",
        backgroundColor: "blue",
        width: "100vw",
        height: "500px",
      }}
    />
  );
};

const LayoutExample = () => {
  return (
    <view
      style={{
        width: "100vw",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        marginTop: "100px",
      }}
    >
      <text
        style={{
          fontSize: "50px",
          padding: "30px",
          background: "red",
        }}
      >
        Hello World
      </text>
      <text
        style={{
          fontSize: "50px",
          marginTop: "50px",
          padding: "30px",
          background: "green",
        }}
      >
        Hello Lynx
      </text>
    </view>
  );
};

export const App = () => {
  const examples: ReactElement[] = [
    <RenderExample />,
    <LayoutExample />,
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">View Examples</text>
      {examples.map((example, index) => example)}
    </scroll-view>
  );
};

```



***

## 2. Managing Example Packages

All interactive examples are managed as dependencies in the `packages/lynx-example-packages/` workspace.

### Directory Structure

```text
packages/lynx-example-packages/
├── package.json          # Manifest listing all example dependencies
├── pnpm-lock.yaml       # Lockfile for examples
└── node_modules/        # Where installed examples reside
    └── @lynx-example/   # Namespace for official examples
```

### Adding a New Example

To make a new example available to the `<Go>` component:

1. **Publish the Package**: Your example must be a valid npm package (e.g., `@lynx-example/my-feature`).
2. **Add Dependency**: Add the package to `packages/lynx-example-packages/package.json`.
3. **Install**: Run `pnpm install` in the workspace root to download the new example.
4. **Rebuild Assets**: The website build process will automatically detect and bundle the new example.

***

## 3. Build Architecture

For those interested in how it works under the hood:

- **Script**: `scripts/lynx-example.js` runs during the build.
- **Process**:
  1. Scans `node_modules/@lynx-example/` for packages.
  2. Identifies bundle files (`.lynx.bundle`, `.web.bundle`) and source code.
  3. Generates an `example-metadata.json` for each example.
  4. Copies assets to `docs/public/lynx-examples/`.
- **Runtime**: The `<Go>` component fetches this metadata at runtime to hydrate the editor and preview.



---
url: /help/index.md
---

# Contributor Guide

Welcome to the Lynx website contributor guide! This documentation project is a large-scale repository that powers the official Lynx documentation. To help you navigate and contribute effectively, we've organized the guidelines into specific topics.

Whether you are writing a blog post, updating API documentation, or adding a new example, this guide will help you understand the tools and conventions we use.

## Catalog

### ✍️ Writing

- [**Guides**](/help/writing.md) - Best practices for page configuration, frontmatter, and writing platform-specific content.
- [**Example**](/help/example.md) - How to add and embed interactive examples using `lynx-example-packages`.
- [**Blog**](/help/blog.md) - How to write and publish blog posts.
- [**Spec**](/help/spec.md) - Guide to editing the Lynx Living Specification.

### 📚 Managing API

- [**API Reference**](/help/api.md) - The source of truth for API references. Learn about `lynx-compat-data`, `<APITable>`, and generating docs with TypeDoc.
- [**API Status**](/help/dashboard.md) - Guide for using the API Status Dashboard tool.

### 🎨 Website UI

- [**Subsites**](/help/subsite.md) - Understanding how the site handles multiple languages and contexts (subsites).
- [**MDX Components References**](/help/components.md) - A "Storybook-style" reference for using built-in components like badges, callouts, and tabs.



---
url: /help/spec.md
---

# Managing Spec

The Lynx Living Specification serves as the definitive technical reference for the Lynx engine.

## Location

The spec source files are located in `packages/lynx-living-spec/`.
The source `.bs` files are specifically in `packages/lynx-living-spec/src/`.

## Format

The spec is written in **Bikeshed** (`.bs`), a preprocessor for specification documents often used by W3C standards.

## Prerequisites

To build the spec, you need to have **Bikeshed** installed. We recommend using `pipx` to install it.

### Install pipx

If you don't have `pipx` installed, you can install it via Homebrew (on macOS):

```bash
brew install pipx
```

### Install Bikeshed

Once `pipx` is installed, install `bikeshed`:

```bash
pipx install bikeshed
```

## Editing the Spec

1. Modify the `.bs` files in `packages/lynx-living-spec/src/`.
   - `index.bs` is the main entry point.
   - Other sections are split into separate files like `styling.bs`, `scripting.bs`, etc.
2. To build the spec locally, run:

```bash
pnpm gen:living-spec
```

This uses a script (`scripts/lynx-living-spec.js`) to invoke `bikeshed` and generate the HTML output at `docs/public/living-spec/index.html`.



---
url: /help/subsite.md
---

# Multi-Subsite Architecture

The Lynx website operates as a collection of "mini-subsites" (e.g., **Lynx**, **ReactLynx**, **Rspeedy**) housed within a single repository. This architecture allows each subsite to have its own identity (logo, home page, sidebar) while sharing common documentation and infrastructure.

## Configuration

The central configuration for subsites is located in [`shared-route-config.ts`](https://github.com/lynx-family/lynx-website/blob/main/shared-route-config.ts). This file acts as the single source of truth for:

1. **Subsite Metadata**: Defines the list of available subsites.
2. **Shared Routes**: Defines which documentation sections are shared across subsites.

### `SubsiteConfig`

Each subsite is defined by a `SubsiteConfig` object:

```typescript
export type SubsiteConfig = {
  value: string; // Unique ID (e.g., 'guide')
  label: string; // Display name (e.g., 'Lynx')
  description: string; // Short description
  home: string; // Root path (e.g., '/')
  url: string; // Landing page URL
  logo: {
    // Logo assets
    light: string;
    dark: string;
  };
};
```

## Adding a New Subsite

To add a new subsite (e.g., `my-framework`):

1. **Create Directory**: Create `docs/en/my-framework/` (and `docs/zh/my-framework/`).
2. **Update Config**: Add a new entry to `SUBSITES_CONFIG` in `shared-route-config.ts`.
   ```typescript
   {
     value: 'my-framework',
     label: 'My Framework',
     // ...
   }
   ```
3. **Configure Sidebar**: Create `docs/en/my-framework/_meta.json` to define its specific sidebar structure.

## Shared Documentation

To avoid duplicating content (like "Quick Start" guides) across multiple subsites, we use a shared documentation system.

### How it Works

1. **Source of Truth**: Shared files are physically located in `docs/en/guide/start/`.
2. **Virtual Routes**: The `sharedSidebarPlugin` in `rspress.config.ts` dynamically creates virtual pages for other subsites (e.g., `react/start/quick-start`) that point to the same content.
3. **Unified Sidebar**: The `BeforeSidebar` component (in `theme/BeforeSidebar.tsx`) automatically injects the shared "Start" section into the sidebar of every subsite.

### Managing Shared Content

To modify which files are shared, update `SHARED_DOC_TITLES` in `shared-route-config.ts`.

```typescript
const SHARED_DOC_TITLES = {
  'quick-start': { en: 'Quick Start', zh: '快速上手' },
  // ...
};
```

## Subsite UI

The subsite navigation and identity are handled by custom theme components:

- **`SubsiteSelect`** (`theme/BeforeSidebar.tsx`): The dropdown menu at the top of the sidebar allows users to switch between subsites.
- **`SubsiteLogo`** (`theme/subsite-ui.tsx`): Renders the correct logo for the current subsite and theme mode.

These components read directly from `SUBSITES_CONFIG`, so any changes there are immediately reflected in the UI.



---
url: /help/writing.md
---

# Authoring Guides

This page outlines the standards and best practices for writing **Guides** on the Lynx website. Guides are narrative documentation designed to teach concepts, explain architecture, or walk users through specific tasks.

For excellent examples of well-structured guides, refer to the [Quick Start](/guide/start/quick-start.md) and [Integrate with Existing Apps](/guide/start/integrate-with-existing-apps.md) pages.

## Page Structure (Frontmatter)

Every guide page is an `.mdx` file that starts with YAML frontmatter to define its metadata.

### `title`

Sets the page title displayed in the sidebar, browser tab, and search results.

```yaml
---
title: Understanding the Lifecycle
---
```

### `context`

Defines the framework or context for the page (e.g., `react`, `vue`, `new`). This is crucial for the **DSL Switcher** feature, which allows users to toggle the documentation view between different framework implementations.

```yaml
---
context: react
---
```

## Writing Tutorials

When writing step-by-step tutorials, use the following components to create a structured and engaging flow.

### `<Steps>`

Use the `<Steps>` component to wrap sequential instructions. This renders a vertical line connecting the steps, improving readability.

<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.



---
url: /index.md
---

# Lynx



---
url: /react/code-splitting.md
---

# Code Splitting

> Rspack supports code splitting, which allows splitting the code into other chunks. You have the full control about size and number of generated assets, which allow you to gain performance improvements in loading time.
>
> [Rspack - Code Splitting](https://rspack.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



---
url: /react/data-fetching.md
---

# Data Fetching

Whether fetching static content from a remote server or interacting with a REST API, ReactLynx applications often need to retrieve data from external sources. For example, you might want to load user posts in a social media app or fetch the latest product listings in an e-commerce application.

Lynx provides the [Fetch API](/api/lynx-api/global/fetch.md), enabling you to make network requests. You can refer to the [Networking](/guide/interaction/networking.md) chapter for more details. The Fetch API provided by Lynx can be used together with server state management libraries from the React ecosystem, such as [TanStack Query (React Query)](https://tanstack.com/query), to simplify data fetching and state management.

It is important to note that Lynx's Fetch API has subtle differences compared to the [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). You can check the [Fetch API Reference - Compatibility](/api/lynx-api/global/fetch.md#compatibility) section to learn more about these differences. As a result, you may need to adapt libraries from the React ecosystem to ensure compatibility. If you encounter any issues on Lynx Fetch API, you are welcome to submit feature requests or [contribute](https://github.com/lynx-family/lynx/blob/develop/CONTRIBUTING.md) to help Lynx better support the React ecosystem.

## Using TanStack Query

TanStack Query is a popular server state management library in the React ecosystem, helping developers easily manage data fetching and caching.

### Installing Dependencies

<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();
}

```





---
url: /react/index.md
---




---
url: /react/introduction.md
---

# What is ReactLynx?

ReactLynx is the official React framework for Lynx. It allows you to develop Lynx native apps with a React mental model.

With ReactLynx, you can build your UI [using JSX and React components](https://react.dev/learn/describing-the-ui), just like you would on the web. ReactLynx turns your React code into calls to the [Lynx Engine](/guide/spec.md#engine) imperative API to render the native UI.

## Main Features

ReactLynx itself is an "idiomatic" React, but it also pioneered optimizations such as "dual-threaded React" and "JSX constant folding".

- **"Idiomatic" React**: ReactLynx is an implementation of React, under the hood it is based on [Preact](https://github.com/preactjs/preact), so it has basically the same API and behavior as React, and this consistency allows many ecosystem constructions to be reused.
- **[Dual-threaded in Mind](/react/thinking-in-reactlynx.md)**: ReactLynx follows the programming model of React, but by utilizing the **dual-threaded runtime** provided by Lynx, combined with its own programming paradigm (or rules) to achieve better performance and user experience.
  - **[Off-main-thread](/guide/spec.md#background-thread-aka-off-main-thread) Reconciliation**: ReactLynx puts some Reconciliation logic into the background thread to reduce the amount of calculation in the main thread and improve performance.
  - **[Lifecycle under dual-thread architecture](/react/lifecycle.md)**: Due to the dual-thread architecture of Lynx, the lifecycle of ReactLynx is slightly different from that of traditional React in terms of calling timing.
- **JSX constant folding**: ReactLynx folds JSX constants at compile time to reduce runtime calculations.

## For React Web Developers

### Change your `import`

Since it has the same API as [`react`](https://www.npmjs.com/package/react), you can directly replace `react` with `@lynx-js/react`, and continue to use the React API you are familiar with.

```diff
- import { useState } from 'react';
+ import { useState } from '@lynx-js/react';
```

For a full list of APIs ReactLynx implemented, please refer to the [`@lynx-js/react` API documentation](/api/react/index.md).

### Different component sets

Unlike elements such as `div` and `span` on the Web, Lynx provides a set of native component sets, such as `view`, `text`, `image`, etc ([full list](/api/elements/built-in/view.md)).
In ReactLynx, you can [combine](/guide/ui/elements-components.md) these elements to build your native UI.

```diff
- <div className="..." />
+ <view className="..." />
```

While the naming of native components is similar to React Native, ReactLynx do have some differences:

```diff
- import {View, Text, Image} from 'react-native';
- <View style={{...}} />
+ <view style={{...}} />
```

### Different event naming

Based on Lynx, ReactLynx uses a different set of event naming than the Web (go to [Events](/guide/interaction/event-handling.md) to learn more).

<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>



---
url: /react/lifecycle.md
---

# Rendering Process and Lifecycle

Due to Lynx's dual-thread architecture, ReactLynx's rendering process and component lifecycle differ from traditional React. This design aims to address mobile performance bottlenecks by properly distributing tasks between threads to ensure rendering performance and interaction fluidity.

## Rendering Process

![Lifecycle Flowchart](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lifecycle-init-render-v3.png)

### First-Screen Rendering Optimization

To solve the slow first-screen loading problem of traditional web applications, Lynx adopts an innovative rendering strategy: when the application starts, the main thread completes the first-screen rendering to ensure the fastest possible initial display. Meanwhile, the background thread performs a parallel rendering and builds a node tree structure, then compares the tree structures from both threads to ensure consistency for handling subsequent updates and synchronizing to the main thread's node tree.

### Dual-Thread Architecture Design

After the first-screen rendering is complete, ReactLynx's dual-thread architecture enhances overall performance through clear responsibility division.
Component lifecycle management and user code execution will only occur in the background thread. After the node tree is updated in the background thread, the background thread will send a message to notify the main thread.
The main thread is responsible for updating the main thread's node tree structure according to instructions from the background thread, calculating layouts, rendering the UI, and executing user-written main thread scripts.

This precise division of labor allows each thread to focus on its core responsibilities, preventing complex user logic from blocking UI responses, ensuring the normal operation of component lifecycles and state management.

### Lifecycle Specifics

In ReactLynx, all lifecycle hooks execute asynchronously in the background thread, so they do not have synchronous blocking render characteristics. This means ReactLynx does not support `useLayoutEffect`. As a current alternative, you can use the element's [`main-thread:bindlayoutchange`](/api/elements/built-in/view.md#bindlayoutchange) event to obtain layout results and set corresponding properties.

Here's a simple example modified from [Measuring layout before the browser repaints the screen](https://react.dev/reference/react/useLayoutEffect#measuring-layout-before-the-browser-repaints-the-screen) to help you use this more easily:

**This is an example below:  react-lifecycle**

**Entry:** `src/measuring-layout`
**Bundle:** `dist/measuring-layout.lynx.bundle` | Web: `dist/measuring-layout.web.bundle`

```tsx {4-18}
import type { PropsWithChildren } from "@lynx-js/react";
import type { Rect } from "./ButtonWithTooltip.jsx";
import TooltipContainer from "./TooltipContainer.jsx";

interface TooltipProps {
  targetRect: Rect | null;
}

export function Tooltip({ children, targetRect }: PropsWithChildren<TooltipProps>) {
  const handleLayoutChange = (e: any) => {
    "main thread";
    let tooltipX = 0;
    let tooltipY = 0;
    if (targetRect !== null) {
      tooltipX = targetRect.left;
      tooltipY = targetRect.top - e.detail.height;
      if (tooltipY < 0) {
        // It doesn't fit above, so place below.
        tooltipY = targetRect.bottom;
      }
    }

    e.currentTarget.setStyleProperty("transform", `translate3d(${tooltipX}px, ${tooltipY}px, 0)`);
  };

  return (
    <TooltipContainer handleLayoutChange={handleLayoutChange}>
      {children}
    </TooltipContainer>
  );
}

```



## Special Characteristics of `<list />` Child Components

The [`<list />`] element has on-demand loading and node reuse characteristics. When a [`<list />`] element is created, all its child component JS object instances are created together, but the corresponding actual elements ([UI]) are not immediately generated. Instead, they are created or reused only when the [`<list />`] is about to scroll to the corresponding position. Therefore, special attention is needed regarding the timing of child component lifecycle triggers.

### Timing of `useEffect` and `ref` Callbacks

The `useEffect` callback function will strictly execute after component creation and data updates; the `ref` attribute will also be assigned when the element is created or destroyed. Even if the component is not displayed on the screen (resulting in the actual [UI] node not being created or having entered the reuse pool), both the `useEffect` callback function and `ref` will still be triggered.

Specifically for [UI] elements inside a [`<list />`], the [`main-thread:ref`] attribute accurately reflects their state. When an element is about to scroll into view, the [`main-thread:ref`] callback function is triggered, and when the element scrolls out of view, the [`main-thread:ref`] cleanup function is triggered.

[`<list />`]: /api/elements/built-in/list.md

[UI]: /guide/spec.md#ui

[`main-thread:ref`]: /react/main-thread-script.md#usingmain-threadref-to-obtain-node-objects



---
url: /react/main-thread-script.md
---

# Main Thread Script

The Main Thread Script is a JS script that can be executed on the main thread. The most common use cases for the main thread script are smooth animations and gesture handling. It is primarily used to address the response delay issue in Lynx's multi-threaded architecture, aiming to achieve a near-native interactive experience.

## Event Response Delay in Lynx

Here is a simple animation: a small square that moves in sync with a `scroll-view`. In the small square component, we listen to the scroll event of the `scroll-view`, retrieve the current scroll position from the event parameters, and update its position immediately:

**This is an example below:  main-thread**

**Entry:** `src/background-draggable`
**Bundle:** `dist/background-draggable.lynx.bundle` | Web: `dist/background-draggable.web.bundle`

```tsx
export function BackgroundDraggable({ size, posStyle }: { size: number; posStyle: { x: number; y: number } }) {
  return (
    <view
      style={{
        height: size + "px",
        width: size + "px",
        background: "lightskyblue",
        transform: `translate(${posStyle.x}px, ${posStyle.y}px)`,
      }}
    >
      <text>BGDraggable</text>
    </view>
  );
}

```



You can try scrolling the scroll-view on the left side of the example. The blue square on the right side of the page will follow the scroll-view's movement. However, you might notice that its movement has an unpredictable delay, especially on devices with lower performance. This delay will also increase as the complexity of the page increases.

This is because in Lynx's architecture, events are triggered on the main thread, while regular JS event handlers can only be executed on background threads. Therefore, if you use regular touch events to trigger animations, the event trigger -> event handling -> rendering process will involve multiple thread switches, resulting in untimely responses and animations lagging behind gestures.

![mts-threads-1.png](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/mts-threads-1.png)

The main thread script provides the capability to handle events synchronously on the main thread, ensuring synchronous event responses.

![mts-threads-2.png](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/mts-threads-2.png)

## Use Main Thread Functions to Eliminate Event Response Delay

### Implementing Animations with Main Thread Script

Synchronizing events using main thread script is very simple. Here we try to modify the previous example.

First, we inform the framework that we want to handle this event on the main thread by adding a main-thread namespace to the event attribute name:

```tsx
<view main-thread:bindscroll={onScroll} />
```

Since the onScroll function is now a main thread event handler, we also need to declare the event handler as a main thread function.
This is done by adding a `main thread` directive as the first line inside the function body:

```ts
let onScroll = (event) => {
  'main thread';
  // ...
};
```

After declaring it as a main thread function, we can no longer call it from the background thread.

Finally, we can now directly manipulate the element's properties on the main thread, so there's no need to use a state to change the position.
When using a main thread function as an event handler, the main thread function accepts an `event` parameter that contains basic information about the event.
The `event.target` and `event.currentTarget` parameters differ from those in regular event handlers;
they are [`MainThread.Element`] objects.
This object allows you to conveniently synchronize the retrieval and setting of node properties, such as using `setStyleProperty()` in the example.

```tsx
let onScroll = (event) => {
  'main thread';
  const detail = event.detail.scrollTop;
  const newPos = {
    x: 0,
    y: 500 - detail,
  };
  event.currentTarget.setStyleProperty(
    'transform',
    `translate(${newPos.x}px, ${newPos.y}px)`,
  );
};
```

That's all the changes needed. We will place the components before and after the modification in the same example for you to compare the effects. You may notice that the animation delay has disappeared!

**This is an example below:  main-thread**

**Entry:** `src/main-thread-draggable`
**Bundle:** `dist/main-thread-draggable.lynx.bundle` | Web: `dist/main-thread-draggable.web.bundle`

```tsx
import type { RefObject } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export function MainThreadDraggable(
  props: { size: number; "main-thread:ref"?: RefObject<MainThread.Element> },
) {
  return (
    <view
      main-thread:ref={props["main-thread:ref"]}
      style={{
        height: props.size + "px",
        width: props.size + "px",
        background: "lightskyblue",
        transform: `translate(0px, 500px)`,
      }}
    >
      <text>MTDraggable</text>
    </view>
  );
}

```



## Retrieving Data from the Background Thread

You may have noticed that designating a function as a main thread function isolates it from its surrounding context, making it feel like an "island."
Its runtime environment is different from other functions, meaning it cannot freely communicate with the background thread or other main-thread scripts.
However, we sometimes still need data from the background thread.

Fortunately, obtaining data from the background thread inside a main thread function is straightforward: just use it directly, as if it were a normal function.

```tsx
export default function App() {
  const red = 'red';

  function addBackgroundColor(event: MainThread.ITouchEvent) {
    'main thread';
    event.currentTarget.setStyleProperty('background-color', red);
  }

  return (
    <view main-thread:bindtap={addBackgroundColor}>
      <text>Hello World!</text>
      <text>Hello World!</text>
    </view>
  );
}
```

When the main thread function is defined, it automatically captures external variables from the background thread,
such as the red variable in the example above.
However, you cannot directly modify the values in the background thread.

The values captured by the main thread function are not updated in real time.
Instead, they are synchronized from the background thread to the main thread only after the component containing the main thread function re-renders.
Additionally, the synchronization requires that the captured values be serializable using `JSON.stringify()`.

To summarize the precautions:

- Main thread functions can and must only run on the main thread. Main thread functions can call each other.
- Captured variables need to be passed between threads using `JSON.stringify()`, so they must be serializable to JSON.
- Main thread functions do not support nested definitions.
- The constructor, getter, and setter of class components do not support being specified as main thread functions.
- You cannot modify variables captured from the external scope within a main thread function.

## Using `main-thread:ref` to Obtain Node Objects

In the example above, clicking on the text would change the color of both lines of text. If we want to change the color of only the first line of text when clicking on the text, it is not easy to achieve this with just `event.target` and `event.currentTarget`. In this case, you can use `main-thread:ref` to obtain a node object usable on the main thread ([`MainThread.Element`]).

Create a [`MainThreadRef`] using the [`useMainThreadRef()`] Hook, and then assign it to the target node's `main-thread:ref` attribute:

```tsx
import { useMainThreadRef } from '@lynx-js/react';

export default function App() {
  const red = 'red';
  const textRef = useMainThreadRef<MainThread.Element>();

  function addBackgroundColor(event: MainThread.ITouchEvent) {
    'main thread';
    textRef.current?.setStyleProperty('background-color', red);
  }

  return (
    <view main-thread:bindtap={addBackgroundColor}>
      <text main-thread:ref={textRef}>Hello World!</text>
      <text>Hello World!</text>
    </view>
  );
}
```

Note that the `current` property of [`MainThreadRef`] can only be accessed within a main thread function.

### Passing a Main Thread Function to `main-thread:ref`

Similar to a regular `ref`, you can also pass a main thread function to `main-thread:ref`:

```tsx
import { useMainThreadRef } from '@lynx-js/react';

export function App() {
  let eleRef = useMainThreadRef<MainThread.Element>();

  function handleTapMainThread() {
    'main thread';
    eleRef.current?.setStyleProperty('height', '30px');
  }

  return (
    <view main-thread:bindTap={handleTapMainThread}>
      <view
        main-thread:ref={(ele: MainThread.Element) => {
          'main thread';
          eleRef.current = ele;
        }}
      />
    </view>
  );
}
```

You can also return a cleanup function in the main thread function passed to `main-thread:ref`, just like when using a regular `ref`.

### Using `main-thread:ref` in Class Components

If you are using traditional class components, you cannot use the [`useMainThreadRef()`] Hook. Instead, you can directly create a [`MainThreadRef`] object:

```tsx
import { MainThreadRef } from '@lynx-js/react';

class App extends Component {
  eleRef = new MainThreadRef<MainThread.Element>();

  handleTapMainThread(event: MainThread.ITouchEvent) {
    'main thread';
    this.eleRef.current?.setStyleProperty('height', '30px');
  }

  render() {
    // ...
  }
}
```

## Maintaining State in Main Thread Functions

Main thread functions cannot modify captured variables. Therefore, if you need to maintain state between main thread functions, you should use [`MainThreadRef`].

For example, changing the background color of a node based on the number of clicks:

```jsx
import { useMainThreadRef } from '@lynx-js/react';

function App() {
  const countRef = useMainThreadRef(0);

  function handleTapMainThread(event: MainThread.ITouchEvent) {
    'main thread';
    event.currentTarget.setStyleProperty('background-color', ++countRef.current % 2 ? 'blue' : 'green');
  }

  return (
    // ...
  );
}
```

## Cross-Thread Function Calls

### 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



---
url: /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.



---
url: /react/react-compiler.md
---

# React Compiler <Experimental />

[React Compiler](https://react.dev/learn/react-compiler) can optimize components at compile time, eliminating the need to manually use `useMemo`, `useCallback`, and `memo`. You can use React Compiler in ReactLynx to enhance your application's performance.

## How to Use

Follow these steps to enable React Compiler for ReactLynx in Rspeedy:

1. Install the runtime dependency for React Compiler:

<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.



---
url: /react/reactlynx-testing-library.md
---

# ReactLynx Testing Library

The [`@lynx-js/react/testing-library`](/api/reactlynx-testing-library/index.md) package provides the same set of APIs (e.g. [`render`](/api/reactlynx-testing-library/Function.render.md), [`fireEvent`](/api/reactlynx-testing-library/Function.fireEvent.md), [`screen`](/api/reactlynx-testing-library/Variable.screen.md), etc.) for testing the rendering result of ReactLynx, just like the popular [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/), with the underlying dual-threaded architecture abstracted away by the [@lynx-js/testing-environment](/api/lynx-testing-environment/index.md).

## Setup

### From create-rspeedy

If you create a new project using [`create-rspeedy`](https://www.npmjs.com/package/create-rspeedy), you can choose whether to use ReactLynx Testing Library (default checked) when creating the project. The created project is already configured with ReactLynx Testing Library.

### Adding to an existing project

ReactLynx Testing Library is integrated in the `testing-library` subdirectory of the `@lynx-js/react` package and can be used directly.

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).



---
url: /react/routing/react-router.md
---

# React Router

React Router enables "single page routing".

### Installation

Since ReactLynx only have React v17 API now, you should install `react-router` v6.

<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.



---
url: /react/routing/tanstack-router.md
---

# TanStack Router

Modern and scalable routing for React applications.

ReactLynx supports both [Memory Routing](https://tanstack.com/router/latest/docs/framework/react/guide/history-types#memory-routing)
and [File-Based Routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing),
where Memory Routing is required due to browser [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) limitations in Lynx,
and File-Based Routing is enabled through seamless `@tanstack/router-plugin/rspack` integration in Rspeedy.

### Installation

Install dependencies:

<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} />;
}

```





---
url: /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.



---
url: /react/state-management/valtio.md
---

# Valtio

## Using `valtio`

[Valtio](https://valtio.dev/) is a simple and powerful proxy-based state management solution, offering fine-grained subscriptions and reactivity.

### Installation

<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.



---
url: /react/state-management/zustand.md
---

# Zustand

## Using `zustand`

[Zustand](https://zustand-demo.pmnd.rs/) is a small, fast, and scalable state management solution with a comfy API based on React Hooks, offering flexibility while maintaining some level of convention.

### Installation

<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.



---
url: /react/thinking-in-reactlynx.md
---

# Thinking in ReactLynx

ReactLynx follows React's programming model, but leverages the _**dual-threaded runtimes**_ provided by Lynx to achieve better performance and user experience through its own idioms (or rules).

## Your code runs on two threads

When the component `<HelloComponent />` is rendered, you will see "Hello" printed twice in the Console.

```jsx
const HelloComponent = () => {
  console.log('Hello'); // This will be printed twice
  return <text>Hello</text>;
};
```

This happens because the code runs on two threads: **main thread** and **background thread**, which are part of Lynx's dual-threaded runtime.

1. The **main thread** is responsible for rendering the initial screen and applying subsequent UI updates.
   This allows users to see the first screen as quickly as possible while reducing the main thread's workload.
2. The **background thread** runs with a complete React runtime, handling component lifecycles and other side effects. Since complete consistency with single-threaded React is not possible, we have a modified component lifecycle as shown in [Component Lifecycle](/react/lifecycle.md).

### Not all code can run on both threads

However, not all code can be executed on both threads.
Consider the following example that adds a listener to `GlobalEventEmitter`:

```jsx
const EventListenerComponent = () => {
  lynx.getJSModule('GlobalEventEmitter').addListener('myHappyEvent', () => {
    console.log('myHappyEvent triggered!');
  });
  return <text>Hello</text>;
};
```

When the component `<EventListenerComponent />` is rendered, you will see a "not a function" error. This occurs because while Lynx renders this component on both threads, `lynx.getJSModule('GlobalEventEmitter')` cannot be executed on the main thread.

<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



---
url: /rspeedy/assets.md
---

# Static Assets

Powered by Rsbuild, Rspeedy supports using static assets, including images, fonts, audios and videos.

:::tip What is Static Assets
Static assets are files that are part of a Lynx application and do not change, even when the application is being used.

Examples of static assets include images, fonts, medias, stylesheets, and JavaScript files. These assets are typically stored on a web server or CDN, and delivered to the users when the Lynx application is accessed.

Because they do not change, static assets can be cached by the App, which helps to improve the performance of the Lynx application.
:::

## Import Assets

You can directly import static assets in JavaScript:

<!-- eslint-disable import/no-unresolved, import/export -->

```jsx
// Import the logo.png image in the static directory
import logo from './static/logo.png';

function App() {
  return <image src={logo} />; // Can be directly used in ReactLynx
}
```

The result of the import will be a URL string that represent the static asset. And the asset will be emitted to the output folder.

You can also use static assets in CSS:

```css
.logo {
  background-image: url('../static/logo.png');
}
```

### URL Prefix

The URL returned after importing a asset will automatically include the path prefix:

- In development, using [`dev.assetPrefix`] to set the path prefix.
- In production, using [`output.assetPrefix`] to set the path prefix.

For example, you can set `output.assetPrefix` to `https://example.com`:

<!-- eslint-disable import/no-unresolved, import/export -->

```js
import logo from './static/logo.png';

console.log(logo); // "https://example.com/assets/logo.6c12aba3.png"
```

### Public Folder

The `public` folder at the project root can be used to place some static assets. These assets will not be bundled by Rspeedy.

- When you start the dev server, these assets will be served under the root path, `/`.
- When you perform a production build, these assets will be copied to the output directory.

In JavaScript code, you can splice the URL via `process.env.ASSET_PREFIX`:

```js
const logoURL = `${process.env.ASSET_PREFIX}/logo.png`;
```

:::warning

- Avoid importing files from the public folder into your source code, instead reference them by URL.
- When referencing resources in the public folder via URL, please use absolute paths instead of relative paths.
- During the production build, the files in public folder will be copied to the output folder (default is `dist`). Please be careful to avoid name conflicts with the output files. When files in the `public` folder have the same name as outputs, the outputs have higher priority and will overwrite the files with the same name in the `public` folder.

:::

### Type Declaration

When you import static assets in TypeScript code, TypeScript may prompt that the module is missing a type definition:

```
TS2307: Cannot find module './static/logo.png' or its corresponding type declarations.
```

To fix this, you need to add a type declaration file for the static assets, please create a `src/rspeedy-env.d.ts` file, and add the corresponding type declaration.

```typescript title=src/rspeedy-env.d.ts
/// <reference types="@lynx-js/rspeedy/client" />
```

## Inline Assets

Inline static assets refer to the practice of including the content of a static asset directly in the JS output, instead of linking to an external file. This can improve the performance of a Lynx application by reducing the number of HTTP requests that Lynx has to make to load the application.

However, static assets inlining also has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Therefore, in the actual scenario, it is necessary to decide whether to use static assets inlining according to the specific situation.

### Automatic Inlining

Rspeedy will inline assets when the file size of is less than a threshold (the default is 2KiB). When inlined, the asset will be converted to a base64-encoded string and will no longer send a separate HTTP request. When the file size is greater than this threshold, it is loaded as a separate file with a separate HTTP request.

The threshold can be modified with the [`output.dataUriLimit`] config.

For example, set the threshold of images to 5000 bytes, and set media assets not to be inlined:

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  output: {
    dataUriLimit: {
      image: 5000,
      media: 0,
    },
  },
});
```

### Force Inlining

You can force an asset to be inlined by adding the `inline` query when importing the asset, regardless of whether the asset's size is smaller than the size threshold.

<!-- eslint-disable import/no-unresolved -->

```js
import img from './foo.png?inline';

console.log(img); // "data:image/png;base64,iVBORw0KGgo..."
```

In the above example, the `foo.png` image will always be inlined, regardless of whether the size of the image is larger than the threshold.

### Force No Inlining

When you want to always treat some assets as separate files, no matter how small the asset is, you can add the `url` query to force the asset not to be inlined.

<!-- eslint-disable import/no-unresolved -->

```js
import img from '. /foo.png?url';

console.log(img); // "/static/foo.fe0bb4d0.png"
```

In the above example, the `foo.png` image will always be loaded as a separate file, even if the size of the image is smaller than the threshold.

## Extend Asset Types

If the built-in asset types in Rsbuild cannot meet your requirements, you can:

- Use the [`source.assetsInclude`] configuration option to specify additional file types to be treated as static assets.
- Modify the built-in Rspack configuration and extend the asset types you need using [`tools.rspack`].

For example, if you want to treat `*.pdf` files as assets and directly output them to the dist directory, you can add the following configuration:

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

// planA: source.assetsInclude
export default defineConfig({
  source: {
    assetsInclude: /\.pdf$/,
  },
});

// planB: tools.rspack
export default defineConfig({
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.pdf$/,
          // converts asset to a separate file and exports the URL address.
          type: 'asset/resource',
        },
      ]);
      return config;
    },
  },
});
```

After adding the above configuration, you can import `*.pdf` files in your code, for example:

<!-- eslint-disable import/no-unresolved -->

```js
import myFile from './static/myFile.pdf';

console.log(myFile); // "/static/myFile.6c12aba3.pdf"
```

For more information about asset modules, please refer to [Rspack - Asset modules](https://rspack.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



---
url: /rspeedy/build-profiling.md
---

# Build Profiling

Performing a performance analysis can help you identify performance bottlenecks in your project, allowing for targeted optimization.

## Using Rsdoctor

Rsdoctor is a build analyser that can visually display the compilation time of each loaders and plugins.

Please refer to [Use Rsdoctor](/rspeedy/use-rsdoctor.md) for more information.

## Node.js Profiling

When Rspeedy executes a build, you can use Node.js profiling to analyze the JavaScript execution, which helps to identify performance bottlenecks.

For example, to perform the [CPU profiling](https://nodejs.org/docs/v20.17.0/api/cli.html#--cpu-prof) analysis, run the following command in the root directory of your project:

```bash
#dev
node --cpu-prof ./node_modules/@lynx-js/rspeedy/bin/rspeedy.js dev

# build
node --cpu-prof ./node_modules/@lynx-js/rspeedy/bin/rspeedy.js build
```

The above commands will generate a `*.cpuprofile` file. We can use [speedscope](https://github.com/jlfwong/speedscope) to visualize this file:

```bash
# Install speedscope
npm install -g speedscope

# View cpuprofile content
# Replace the name with the local file name
speedscope CPU.date.000000.00000.0.001.cpuprofile
```

## Rspack profiling

Rspeedy supports the use of the `RSPACK_PROFILE` environment variable for Rspack build performance profiling.

```bash
# dev
RSPACK_PROFILE=ALL rspeedy dev

# build
RSPACK_PROFILE=ALL rspeedy build
```

This command will generate a `rspack-profile-${timestamp}` folder in the dist folder, and it will contain `logging.json`, `trace.json` and `jscpuprofile.json` files:

- `trace.json`: The time spent on each phase of the Rust side is recorded at a granular level using tracing and can be viewed using [ui.perfetto.dev](https://ui.perfetto.dev/).
- `jscpuprofile.json`: The time spent at each stage on the JavaScript side is recorded at a granular level using [Node.js inspector](https://nodejs.org/dist/latest-v18.x/docs/api/inspector.html) and can be viewed using [speedscope.app](https://www.speedscope.app/).
- `logging.json`: Includes some logging information that keeps a coarse-grained record of how long each phase of the build took. (Not supported in development environment yet)

> For more information about Rspack build performance analysis usage, please refer to [Rspack - Profiling](https://web-infra-dev.github.io/rspack-dev-guide/profiling/intro.html#profiling).



---
url: /rspeedy/cli.md
---

# CLI

Rspeedy comes with a lightweight CLI that includes commands such as `dev` and `build`.

## Using the global Rspeedy version

You can invoke Rspeedy using `npx rspeedy`, but it's more convenient to also install it globally so that it's always available in your shell `PATH`:

```bash
# Install the Rspeedy globally
npm install --global @lynx-js/rspeedy
```

:::info What if the globally installed Rspeedy binary is the wrong version?

Just like [Rush](https://rushstack.io/), Rspeedy implements a "version selector" feature that will automatically discover your local `node_modules` folder and invoke `./node_modules/.bin/rspeedy`, ensuring that the correct version is used.
:::

## Using Node.js TypeScript support

If the version of Node.js you are using supports TypeScript:

1. Node.js >= v23.6
2. Node.js >= v22.6 with [--experimental-strip-types](https://nodejs.org/api/cli.html#--experimental-strip-types)
3. Node.js >= v22.7 with [--experimental-transform-types](https://nodejs.org/api/cli.html#--experimental-transform-types)

you can use the built-in TS transformation of Node.js.

```json title="package.json"
{
  "build": "NODE_OPTIONS=--experimental-transform-types rspeedy build"
}
```

See [Node.js - TypeScript](https://nodejs.org/api/typescript.html) for more details.

## rspeedy -h

To view all available CLI commands, run the following command in the project directory:

```bash
rspeedy -h
```

The output is shown below:

```text
➜ rspeedy --help

Usage: rspeedy <command> [options]

Options:
  -V, --version      output the version number
  --unmanaged        Force to use the unmanaged version of Rspeedy, instead of the locally installed.
  -h, --help         display help for command

Commands:
  build [options]    Build the project in production mode
  dev [options]      Run the dev server and watch for source file changes while serving.
  inspect [options]  View the Rsbuild config and Rspack config of the project.
  preview [options]  Preview the production build outputs locally.
  help [command]     display help for command
```

## rspeedy dev

The `rspeedy dev` command is used to start a local dev server and compile the source code for development.

```text
➜ rspeedy dev --help

Usage: rspeedy dev [options]

Run the dev server and watch for source file changes while serving.

Options:
  --base <base>            specify the base path of the server
  --environment <name...>  specify the name of environment to build
  -c --config <config>     specify the configuration file, can be a relative or absolute path
  --env-mode <mode>        specify the env mode to load the .env.[mode] file
  --no-env                 disable loading `.env` files"
  -m --mode <mode>         specify the build mode, can be `development`, `production` or `none`
  -h, --help               display help for command
```

The dev server will restart automatically when the content of the configuration file is modified.

## rspeedy build

The `rspeedy build` command will build the outputs for production in the `dist/` directory by default.

```text
➜ rspeedy build --help

Usage: rspeedy build [options]

Build the project in production mode

Options:
  --environment <name...>  specify the name of environment to build
  --watch                  Enable watch mode to automatically rebuild on file changes
  -c --config <config>     specify the configuration file, can be a relative or absolute path
  --env-mode <mode>        specify the env mode to load the .env.[mode] file
  --no-env                 disable loading `.env` files"
  -m --mode <mode>         specify the build mode, can be `development`, `production` or `none`
  -h, --help               display help for command
```

## rspeedy preview

The `rspeedy preview` command is used to preview the production build outputs locally. Note that you need to execute the `rspeedy build` command beforehand to generate the build outputs.

```text
➜ rspeedy preview --help

Usage: rspeedy preview [options]

Preview the production build outputs locally.

Options:
  --base <base>         specify the base path of the server
  -c --config <config>  specify the configuration file, can be a relative or absolute path
  --env-mode <mode>     specify the env mode to load the .env.[mode] file
  --no-env              disable loading `.env` files"
  -m --mode <mode>      specify the build mode, can be `development`, `production` or `none`
  -h, --help            display help for command
```

:::tip
The preview command is only used for local preview. Do not use it for production servers, as it is not designed for that.
:::

## rspeedy inspect

The `rspeedy inspect` command is used to view the Rspeedy config and Rspack config of the project.

```text
➜ rspeedy inspect --help

Usage: rspeedy inspect [options]

View the Rsbuild config and Rspack config of the project.

Options:
  --output <output>     specify inspect content output path
  --verbose             show full function definitions in output
  -c --config <config>  specify the configuration file, can be a relative or absolute path
  --env-mode <mode>     specify the env mode to load the .env.[mode] file
  --no-env              disable loading `.env` files"
  -m --mode <mode>      specify the build mode, can be `development`, `production` or `none`
  -h, --help            display help for command
```

When you run the command `rspeedy inspect` in the project root directory, the following files will be generated in the `dist/.rspeedy` directory of the project:

- `rspeedy.config.js`: Represents the Rspeedy configuration used during the build.
- `rsbuild.config.mjs`: Represents the Rsbuild configuration used during the build.
- `rspack.config.lynx.mjs`: Represents the Rspack configuration used during the build.

```text
➜ rspeedy inspect

Inspect config succeed, open following files to view the content:

  - Rspeedy Config: /project/dist/.rsbuild/rspeedy.config.mjs
  - Rspack Config (lynx): /project/dist/.rsbuild/rspack.config.lynx.mjs

Inspect Rspeedy config succeed, open following files to view the content:

  - Rspeedy: /Users/colin/rspeedy/examples/react/dist/rspeedy-rspack/.rsbuild/rspeedy.config.js
```

### Specifying Mode

By default, the inspect command outputs the configuration for the development mode. You can add the `--mode production` option to output the configuration for the production mode:

```bash
rspeedy inspect --mode production
```

### Verbose content

By default, the inspect command omits the content of functions in the configuration object. You can add the `--verbose` option to output the complete content of functions:

```bash
rspeedy inspect --verbose
```



---
url: /rspeedy/index.md
---




---
url: /rspeedy/output.md
---

# Output Files

This chapter will introduces the directory structure of output files and how to control the output directory of different types of files.

## Default Directory Structure

The following is a basic directory for output files. By default, the compiled files will be output in the `dist` directory of current project.

### Production

In production, the `dist/` directory contains all the files that need to be deployed.

```txt
dist/
├── [name].lynx.bundle
├── async
│   └── [name].lynx.bundle
└── static
    ├── image
    │   └── [name].[hash].png
    ├── svg
    │   └── [name].[hash].svg
    └── js
        ├── [id].[hash].js
        │   └── async
        │       └── [id].[hash].js
        └── lib-preact.[hash].js
```

The most common output files are Bundle files, JS files and static assets:

- Bundle files(`[name].lynx.bundle`), which can be configured with [`output.filename.bundle`].
- Async(lazy) bundle files(`async/[name].lynx.bundle`).
- JS files(`static/js/*.js`), which can be configured with [`output.distPath.js`] and [`output.filename.js`].
- Static assets(`static/{font,image,media,svg}`) directory.

In the filename, `[name]` is the entry name corresponding to this file, such as `index`, `main`. `[hash]` is the hash value generated based on the content of the file. `[id]` is the internal chunk ID of Rspack.

### Development

In development, an `dist/.rspeedy` directory is emitted which contains the resources for debugging.

```txt
dist/
├── .rspeedy
│   ├── async
│   │   └── [name]
│   │       ├── debug-info.json
│   │       ├── tasm.json
│   │       └── [name].css
│   ├── [name]
│   │   ├── background.js
│   │   ├── background.js.map
│   │   ├── debug-info.json
│   │   ├── [name].css
│   │   ├── main-thread.js
│   │   ├── main-thread.js.map
│   │   └── tasm.json
│   └── rspeedy.config.js
├── [name].lynx.bundle
└── static
    ├── image
    │   ├── [name].[hash].png
    │   └── [name].[hash].svg
    └── js
        ├── [id].[hash].js
        │   └── async
        │       ├── [id].[hash].js
        │       └── [id].[hash].js.map
        ├── lib-preact.[hash].js
        └── lib-preact.[hash].js.map
```

In addition, Rspeedy generates some extra files in development:

- Background Thread Script(BTS): The background script file that is inlined into the bundle, default output to `.rspeedy/[name]/background.js`.
- MainThread Thread Script(MTS): The main-thread script file that is inlined into the bundle, default output to `.rspeedy/[name]/main-thread.js`.
- Source Map files: contains the source code mappings, which is output to the same level directory of JS files and adds a `.map` suffix.

## Modify the Directory

Rspeedy provides some configs to modify the directory or filename, you can:

- Modify the filename through [`output.filename`].
- Modify the output path of through [`output.distPath`].
- Modify the license file through [`output.legalComments`].
- Modify Source Map file through [`output.sourceMap`].

## Flatten the Directory

Sometimes you don't want the dist directory to have too many levels, you can set the directory to an empty string to flatten the generated directory.

See the example below:

```js
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  output: {
    distPath: {
      js: '',
    },
    filename: {
      bundle: '[name].lynx.bundle',
    },
  },
});
```

The above config produces the following directory structure:

```bash
dist
├── [id].[hash].js
├── [id].[hash].js.map
└── [name].lynx.bundle
```

[`output.filename`]: /api/rspeedy/rspeedy.output.filename.md

[`output.filename.js`]: /api/rspeedy/rspeedy.filename.md

[`output.filename.bundle`]: /api/rspeedy/rspeedy.filename.bundle.md

[`output.distPath`]: /api/rspeedy/rspeedy.output.distpath.md

[`output.distPath.js`]: /api/rspeedy/rspeedy.distpath.md

[`output.legalComments`]: /api/rspeedy/rspeedy.output.legalcomments.md

[`output.sourceMap`]: /api/rspeedy/rspeedy.output.sourcemap.md



---
url: /rspeedy/plugin.md
---

# Plugin

Rsbuild provides a powerful plugin system that allows for user extension.
Rspeedy leverages this plugin system directly.

Plugins written by developers can modify the default behavior of Rspeedy/Rsbuild and add various additional features, including but not limited to:

- Register lifecycle hooks
- Transform module source code
- Modify Rsbuild configuration
- Modify Rspack configuration

## Find Plugins

Before finding plugin, you may want to check if the feature you want is already included in [Rspeedy Configuration](/api/rspeedy/rspeedy.md).

### Rsbuild Plugins

The following Rsbuild plugins can be used in Rspeedy.

- [Sass Plugin](https://rsbuild.dev/plugins/list/plugin-sass): Use Sass as the CSS preprocessor.
- [Less Plugin](https://rsbuild.dev/plugins/list/plugin-less): Use Less as the CSS preprocessor.
- [ESLint Plugin](https://github.com/rspack-contrib/rsbuild-plugin-eslint): Run ESLint checks during the compilation.
- [Type Check Plugin](https://github.com/rspack-contrib/rsbuild-plugin-type-check): Run TypeScript type checker on a separate process.
- [Image Compress Plugin](https://github.com/rspack-contrib/rsbuild-plugin-image-compress): Compress the image assets.
- [Typed CSS Modules Plugin](https://github.com/rspack-contrib/rsbuild-plugin-typed-css-modules): Generate TypeScript declaration file for CSS Modules.
- [Tailwind CSS Plugin](https://github.com/rspack-contrib/rsbuild-plugin-tailwindcss): Integrate with Tailwind CSS V3

### Rspack/Webpack Plugins

The following Rspack/Webpack plugins can be used in Rspeedy.

:::info
Rspack/Webpack plugins should be placed in [`tools.rspack.plugins`].
:::

- [BannerPlugin]: Add a banner to the top or bottom of the output.
- [EnvironmentPlugin]: Use `process.env` with [DefinePlugin].
- [ProvidePlugin]: Automatically load modules instead of having to `import` them everywhere.

## Write Plugins

If none of the existing ecosystem plugins meet your requirements, you might consider writing your own plugin.

### Rsbuild Plugin API

See [Rsbuild - Plugin Hooks](https://rsbuild.dev/plugins/dev/hooks) for more details.

### Rspack Plugin API

See [Rspack - Compiler Hooks](https://rspack.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



---
url: /rspeedy/resolve.md
---

# Module Resolution

In modern front-end development, modularity has become a key approach to managing code effectively:

1. **Simplified Module Imports**:

   - Module resolution allows you to use concise and more readable paths for importing modules, instead of cumbersome relative paths. For example, with an alias configuration, you can use `@components/Button` instead of `../../../src/components/Button`, which significantly improves code maintainability.

2. **Environment-Aware Module Substitution**:
   - Module resolution enables you to load different versions of modules based on the environment (e.g., development and production or Lynx and browser). You can easily achieve environment-aware module substitution, ensuring that the most appropriate dependencies are used in different scenarios.

## Path Aliases

Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.

For example, if you frequently reference the `src/common/request.ts` module in your project, you can define an alias for it as `@request` and then use `import request from '@request'` in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.

### Using `tsconfig.json`'s `paths` Configuration

You can configure aliases through the `paths` configuration in `tsconfig.json`, which is the recommended approach in TypeScript projects as it also resolves the TS type issues related to path aliases.

For example:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common/*"]
    }
  }
}
```

After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.

:::tip
You can refer to the [TypeScript - paths](https://typescriptlang.org/tsconfig#paths) documentation for more details.
:::

### Use `source.alias` Configuration

Rsbuild provides the [source.alias](/api/rspeedy/rspeedy.source.alias.md) configuration option, which corresponds to the webpack/Rspack native [resolve.alias](https://rspack.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



---
url: /rspeedy/runtime-profiling.md
---

# Runtime Profiling

## Profiling Lynx

Following the instruction of [Record Trace](/guide/devtool/trace/record-trace.md) to profiling Lynx.

## Profiling Framework

You can analyze framework performance in two ways: via build configuration and using the [JS Profile](/guide/devtool/trace/js-profile.md).

### Enabling via Build Configuration

We provide the builtin trace points in frameworks like ReactLynx (Components' `render` and `diff`).

![react profile](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/rspeedy-react-profile.png)

- In development(`rspeedy dev`): ReactLynx-related trace points are _**added**_ by default.
- In production(`rspeedy build`): ReactLynx-related trace points are _**removed**_ by default.

These tracing points show how components are rendered and diffed.

#### Run profiling in production

The trace points can be enabled by setting the [`performance.profile`] to `true` when build.

```js
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  performance: {
    // [!code ++]
    profile: true, // [!code ++]
  }, // [!code ++]
});
```

:::tip
You may use [`rspeedy preview`](/rspeedy/cli.md#rspeedy-preview) to preview the output locally.
:::

This is useful when trying to optimize the performance of the application.

:::warning
Do **NOT** deploy the output with `performance.profile: true`. They are not for production.
:::

#### Disable profiling in development

The trace points can be disabled by setting the [`performance.profile`] to `false` when dev.

```js
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  performance: {
    // [!code ++]
    profile: false, // [!code ++]
  }, // [!code ++]
});
```

### Dynamic Sampling with JS Profile

Use the [JS Profile](/guide/devtool/trace/js-profile.md) tool to collect call stack data at runtime without modifying the build configuration.

[`performance.profile`]: /api/rspeedy/rspeedy.performance.profile.md



---
url: /rspeedy/styling.md
---

# Styling

Rspeedy supports different ways of styling your application, including:

- [**CSS Modules**](#using-css-modules): Create locally scoped CSS classes to avoid naming conflicts and improve maintainability.

- [**Global CSS**](#using-global-css): Simple to use and familiar for those experienced with traditional CSS, but can lead to larger CSS bundles and difficulty managing styles as the application grows.

- [**CSS pre-processors**](#using-css-pre-processors): Popular CSS pre-processors like [`sass`](https://sass-lang.com/) and [`less`](https://lesscss.org/) that extend CSS with features like variables, nested rules, and mixins.

- [**PostCSS**](#using-postcss): A tool for transforming CSS.

- [**Tailwind CSS**](#using-tailwind-css): A utility-first CSS framework that allows for rapid custom designs by composing utility classes.

## Using CSS Modules

[CSS Modules](https://github.com/css-modules/css-modules) allows us to write CSS code in a modular way, and these styles can be imported and used in JavaScript files. Using CSS Modules can automatically generate unique class names, isolate styles between different modules, and avoid class name conflicts.

:::tip
You can use [Global CSS](#using-global-css) if you want some of the CSS to be non-isolated.
:::

Rspeedy supports CSS Modules by default, you don't need to add additional configuration. Our convention is to use the `[name].module.css` filename to enable CSS Modules.

### Example

1. Write styles as usual:

```css title=button.module.css
.red {
  background: red;
}
```

2. Use styles like a module:

```jsx title=Button.jsx
import styles from './button.module.css';

export function Button() {
  return (
    <view className={styles.red}>
      <text>Button</text>
    </view>
  );
}
```

Or, you can use **Named Imports**:

```jsx title=Button.jsx
import { red } from './button.module.css';

export function Button() {
  return (
    <view className={red}>
      <text>Button</text>
    </view>
  );
}
```

### With CSS Pre-Processor

The CSS Modules can also be used with [CSS Pre-Processor](#using-css-pre-processors). Just name your files with the pattern `*.module.*`.

E.g.: the following style files are considered CSS Modules:

- `*.module.css`
- `*.module.less`
- `*.module.sass`
- `*.module.scss`
- `*.module.styl` {/* <!-- cspell:disable-line --> */}
- `*.module.stylus`

### Recognition Rules

By default, only files ending with `*.module.{css,scss,less}` are recognized as CSS Modules.

If you want to treat other CSS files as CSS Modules as well, you can achieve this by configuring [output.cssModules.auto](/api/rspeedy/rspeedy.cssmodules.auto.md). {/* cspell:disable-line */}

For example:

```js title=lynx.config.ts
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  output: {
    cssModules: {
      auto(filename) {
        return filename.includes('.module.') || filename.includes('/shared/');
      },
    },
  },
});
```

Given this configuration, the following imports will be recognized as CSS Modules:

```js
import * as foo from './foo.module.css';
import * as bar from './shared/bar.css';
```

### Type Declaration

When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:

```
TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
```

To fix this, you need to add a type declaration file for the CSS Modules, please create a `src/rspeedy-env.d.ts` file, and add the corresponding type declaration.

```typescript title=src/rspeedy-env.d.ts
/// <reference types="@lynx-js/rspeedy/client" />
```

:::tip
[`create-rspeedy`](https://npmjs.com/create-rspeedy) will automatically create this file for you.
:::

If type errors still exist after adding the type declaration, you can try to restart the current IDE. Making sure the TypeScript can correctly identify the type definition.

#### Generate exact type declaration

The `@lynx-js/rspeedy/client` will give type declarations like this:

```ts
declare module '*.module.css' {
  type CSSModuleClasses = {
    readonly [key: string]: string;
  };
  const classes: CSSModuleClasses;
  export default classes;
}
```

Using [Typed CSS Modules Plugin](https://github.com/rspack-contrib/rsbuild-plugin-typed-css-modules) with Rspeedy will generate type declaration files for all CSS Modules with exact type declarations.

1. Install the `@rsbuild/plugin-typed-css-modules` package

<PackageManagerTabs command="add -D @rsbuild/plugin-typed-css-modules" />

2. Add the `pluginTypedCSSModules` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginTypedCSSModules } from '@rsbuild/plugin-typed-css-modules';

import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [pluginReactLynx(), pluginTypedCSSModules()],
});
```

After running `rspeedy build` or `rspeedy dev`, the type declarations will be generated.

```ts title=button.module.css.d.ts
// This file is automatically generated.
// Please do not change this file!
interface CssExports {
  red: string;
}
export const cssExports: CssExports;
export default cssExports;
```

You may also need to add [`"allowArbitraryExtensions": true`](https://www.typescriptlang.org/tsconfig/#allowArbitraryExtensions) and [`"moduleResolution": "Bundler"`](https://www.typescriptlang.org/tsconfig/#moduleResolution) to `tsconfig.json`.

```json title=tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "allowArbitraryExtensions": true
  }
}
```

## Using Global CSS

In some case, you may want the CSS styles to be used with some complex selector. It is called Global CSS in ReactLynx.

Just write CSS code and imported from a javascript file.

### Example

1. Write styles as usual:

```css title=styles.css
.red {
  background: red;
}

.red > text {
  color: blue;
}
```

2. Import the `.css` file from the JSX file and use the CSS classes:

```jsx title=index.jsx
import './styles.css';

export default function App() {
  return (
    <view className="red">
      <text>Hello, Rspeedy!</text>
    </view>
  );
}
```

## Using CSS Pre-Processors

CSS pre-processors extend CSS with features like variables, nested rules, and mixins.

### Using `sass`

1. Install the `@rsbuild/plugin-sass` package

<PackageManagerTabs command="install -D @rsbuild/plugin-sass" />

2. Add the `pluginSass` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginSass } from '@rsbuild/plugin-sass';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [
    pluginSass({
      /** sass options */
    }),
  ],
});
```

Then simply create `.scss` or `.sass` files and import them into JavaScript.

```jsx
import './global.sass';
import styles from './button.module.scss';

export function App() {
  return (
    <view className={styles.red}>
      <text className="title">Hello, Sass</text>
    </view>
  );
}
```

More options can be used in `pluginSass`, please refer to [Sass Plugin](https://rsbuild.dev/plugins/list/plugin-sass) for usage.

### Using `less`

1. Install the `@rsbuild/plugin-less` package

<PackageManagerTabs command="install -D @rsbuild/plugin-less" />

2. Add the `pluginLess` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginLess } from '@rsbuild/plugin-less';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [
    pluginLess({
      /** less options */
    }),
  ],
});
```

Then simply create `.less` files and import them into JavaScript.

```jsx
import './global.less';
import styles from './button.module.less';

export function App() {
  return (
    <view className={styles.red}>
      <text className="title">Hello, Less</text>
    </view>
  );
}
```

More options can be used in `pluginLess`, please refer to [Less Plugin](https://rsbuild.dev/plugins/list/plugin-less) for usage.

### Using `stylus`

1. Install the `@rsbuild/plugin-stylus` package

<PackageManagerTabs command="install -D @rsbuild/plugin-stylus" />

2. Add the `pluginStylus` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginStylus } from '@rsbuild/plugin-stylus';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [
    pluginStylus({
      /** stylus options */
    }),
  ],
});
```

More options can be used in `pluginStylus`, please refer to [Stylus Plugin](https://rsbuild.dev/plugins/list/plugin-stylus) for usage.

## Using PostCSS

Powered by Rsbuild, Rspeedy has built-in [PostCSS](https://postcss.org/) to transform the CSS code.

Rsbuild uses [postcss-load-config](https://github.com/postcss/postcss-load-config) to load the PostCSS configuration file in the root directory of the current project, such as `postcss.config.js`:

```js
export default {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
    },
  },
};
```

## Using Tailwind CSS

1. Installing Tailwind CSS

   Rspeedy has built-in support for PostCSS, you can install tailwindcss package to integrate Tailwind CSS:

   <PackageManagerTabs command="install -D tailwindcss@^3" />

2. Configuring PostCSS

   You can register the tailwindcss PostCSS plugin through [`postcss.config.js`](https://www.npmjs.com/package/postcss-loader#config) or [`tools.postcss`](https://rsbuild.rs/config/tools/postcss).

   ```js title=postcss.config.js
   export default {
     plugins: {
       tailwindcss: {},
     },
   };
   ```

3. Installing the `@lynx-js/tailwind-preset` package:

   <PackageManagerTabs command="install -D @lynx-js/tailwind-preset" />

4. Configuring `tailwind.config.js` and adding `@lynx-js/tailwind-preset`:

   You must use [`@lynx-js/tailwind-preset`](https://github.com/lynx-family/lynx-stack/tree/main/packages/third-party/tailwind-preset) to remove all the tailwindcss utilities not supported in Lynx or adapt to Lynx-specific alternatives.

   ```js title=tailwind.config.js
   import lynxPreset from '@lynx-js/tailwind-preset';

   export default {
     content: ['./src/**/*.{js,ts,jsx,tsx}'],
     presets: [lynxPreset],
   };
   ```

   :::warning

   `@lynx-js/tailwind-preset` is still not stable, please use it with caution. If you found any tailwindcss features that are not working and should be supported, please open an issue at [https://github.com/lynx-family/lynx-stack/issues](https://github.com/lynx-family/lynx-stack/issues).

   :::

### Example


**This is an example below:  tailwindcss**

**Entry:** `src`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useEffect } from "@lynx-js/react";

import "./App.css";

export function App() {
  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  return (
    <page>
      <view className="flex flex-col justify-center items-center min-h-screen text-center">
        <text className="text-6xl font-bold leading-normal underline">
          ReactLynx + TailwindCSS
        </text>
        <text className="text-lg font-normal text-gray-500 leading-normal">
          Start building amazing things with ReactLynx.
        </text>
        <view
          className="flex flex-row p-20 rounded-full"
          style={{
            backgroundColor: "rgba(255, 255, 255, 0.5)",
            padding: "40px",
            margin: "10px",
          }}
        >
          <image
            src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=320&h=320&q=80"
            className="mt-8 rounded-full w-16 h-16 translate-x-6"
            style={{
              marginRight: "40px",
            }}
          />
          {/* static should not be supported */}
          <image
            src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=320&h=320&q=80"
            className="mt-8 rounded-full w-16 h-16 rotate-45 static"
            style={{
              marginRight: "40px",
            }}
          />
          {/* static should be supported */}
          <image
            src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=320&h=320&q=80"
            className="mt-8 rounded-full w-16 h-16 scale-150 sticky"
            style={{
              marginRight: "40px",
            }}
          />
        </view>
        <view className="grid grid-cols-3 gap-4">
          <text>01</text>
          <text>02</text>
          <text>03</text>
          <text>04</text>
          <text>05</text>
          <text>06</text>
        </view>
      </view>
    </page>
  );
}

```





---
url: /rspeedy/typescript.md
---

# TypeScript

Powered by Rsbuild, Rspeedy supports TypeScript by default, allowing you to directly use `.ts` and `.tsx` files in your projects.

## Path Alias

Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.

For example, if you frequently reference the `src/common/request.ts` module in your project, you can define an alias for it as `@request` and then use import request from `'@request'` in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.

The [`paths`](https://www.typescriptlang.org/tsconfig/#paths) option of TypeScript is recommended to be used to make path aliases.

```json title=tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common/*"]
    }
  }
}
```

After configuring, if you reference `@common/request.ts` in your code, it will be mapped to the `<project>/src/common/request.ts` path.

<!-- eslint-disable-next-line import/no-unresolved -->

```js
import { get } from '@common/request.js'; // The same as './common/request.js'
```

## Custom `tsconfig.json` Path

Rspeedy by default reads the `tsconfig.json` file from the root directory. You can use the [source.tsconfigPath](/api/rspeedy/rspeedy.source.tsconfigpath.md) to configure a custom tsconfig.json file path.

```ts
export default {
  source: {
    tsconfigPath: './tsconfig.custom.json',
  },
};
```

## Rspeedy type declaration

Rspeedy provide various built-in features like CSS Modules and [Static Assets](/rspeedy/assets.md). TypeScript does not know about these features and the corresponding type declarations.

To solve this, create a `src/rspeedy-env.d.ts` file, and add the following content:

```typescript title=src/rspeedy-env.d.ts
/// <reference types="@lynx-js/rspeedy/client" />
```

:::tip
[`create-rspeedy`](https://npmjs.com/create-rspeedy) will automatically create this file for you.
:::

## Extending Lynx types

Lynx provides default types, but you may need to extend or customize certain type definitions for your application.

- [`GlobalProps`](#globalprops): extends the type definition for `lynx.__globalProps`
- [`InitData`](#initdata): extends the return type of [`useInitData()`](/api/react/Function.useInitData.md)
- [`IntrinsicElements`](#intrinsicelements): extends the type definition for elements (e.g: you may have your own `<input>` element)
- [`NativeModules`](#nativemodules): extends the type definition for [custom native modules](/guide/use-native-modules.md).

### GlobalProps

You can extend the `interface GlobalProps` from `@lynx-js/types` to add custom properties:

```ts title="src/global-props.d.ts"
declare module '@lynx-js/types' {
  interface GlobalProps {
    foo: string;
    bar: number;
  }
}

export {}; // This export makes the file a module
```

After this extension, TypeScript will recognize and provide type checking for `lynx.__globalProps.foo` and `lynx.__globalProps.bar`.

### InitData

You can extend the `interface InitData` from `@lynx-js/react` to add your custom data properties:

```ts title="src/init-data.d.ts"
declare module '@lynx-js/react' {
  interface InitData {
    foo: string;
    bar: number;
  }
}

export {}; // This export makes the file a module
```

With this extension, TypeScript will provide type checking for `useInitData().foo` and `useInitData().bar` in your components.

### IntrinsicElements

You can extends the `interface IntrinsicElements` from `@lynx-js/types` to add your [custom native element](/guide/custom-native-component.md)

Here is an example for a `<input>` element with required `type` and optional `bindinput` and `value`.

```ts title="src/intrinsic-element.d.ts"
import * as Lynx from '@lynx-js/types';

declare module '@lynx-js/types' {
  interface IntrinsicElements extends Lynx.IntrinsicElements {
    input: {
      bindinput?: (e: { type: 'input'; detail: { value: string } }) => void;
      type: string;
      value?: string | undefined;
    };
  }
}
```

### NativeModules

You can extend the `interface NativeModules` from `@lynx-js/types` to add custom [native modules](/guide/use-native-modules.md):

Here is an example for a `NativeLocalStorageModule` with 3 methods:

```ts title="src/native-modules.d.ts"
declare module '@lynx-js/types' {
  interface NativeModules {
    NativeLocalStorageModule: {
      clearStorage(): void;
      getStorageItem(key: string): string | null;
      setStorageItem(key: string, value: string): void;
    };
  }
}

export {}; // This export makes the file a module
```

## TypeScript Transpilation

Rsbuild uses SWC for transforming TypeScript code.

### isolatedModules

Unlike the native TypeScript compiler, tools like SWC and Babel compile each file separately and cannot determine whether an imported name is a type or a value. Therefore, when using TypeScript in Rspeedy, you need to enable the [isolatedModules](https://typescriptlang.org/tsconfig/#isolatedModules) option in your `tsconfig.json` file:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "isolatedModules": true // [!code focus]
  }
}
```

:::tip
[`create-rspeedy`](https://npmjs.com/create-rspeedy) will automatically include this for you.
:::

This option can help you avoid using certain syntax that cannot be correctly compiled by SWC and Babel, such as cross-file type references. It will guide you to correct the corresponding usage:

<!-- eslint-disable import/no-unresolved, import/export -->

```ts
// ❌ Wrong
export { SomeType } from './types.js';

// ✅ Correct
export type { SomeType } from './types.js';

// ✅ Correct
export { type SomeType } from './types.js';
```

## Type Checking

Type checking is not performed.

Rsbuild provides the [Type Check plugin](https://rsbuild.rs/guide/basic/typescript#type-checking), which runs TypeScript type checking in a separate process. The plugin internally integrates [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin).

1. Install the `@rsbuild/plugin-type-check` package

```bash
pnpm add -D @rsbuild/plugin-type-check
```

2. Add `@rsbuild/plugin-type-check` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginTypeCheck } from '@rsbuild/plugin-type-check';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  plugins: [
    pluginTypeCheck({
      enable: true,
    }),
  ],
});
```

Please refer to the [Type Check plugin](https://rsbuild.rs/guide/basic/typescript#type-checking) for more available options.



---
url: /rspeedy/upgrade.md
---

# Upgrade Rspeedy

This section explains how to upgrade the project's Rspeedy-related dependencies.

## Use `upgrade-rspeedy`

The Rspeedy project includes several NPM packages with `peerDependencies` constraints. Unmatched `peerDependencies` can lead to compilation and runtime errors.

We recommend using the [`upgrade-rspeedy`](https://npmjs.org/package/upgrade-rspeedy) tool to upgrade the Rspeedy version.

:::info
The `upgrade-rspeedy` command will not install dependencies for you.

Please remember to install the dependencies with your package manager.
:::

### Upgrade to the `latest` version (recommended)

To upgrade `@lynx-js/rspeedy` and its plugins to the latest version, use the following command in your project:

<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
```



---
url: /rspeedy/use-rsdoctor.md
---

# Use Rsdoctor

[Rsdoctor](https://rsdoctor.dev/) is a build analyzer that can visually display the build process, such as compilation time, code changes before and after compilation, module reference relationships, duplicate modules, etc.

If you need to debug the build outputs or build process, you can use Rsdoctor for troubleshooting.

- Rsdoctor is a one-stop tool for diagnosing and analyzing the build process and build artifacts.
- Rsdoctor is a tool that supports Webpack and Rspack build analysis.
- Rsdoctor is an analysis tool that can display the time-consuming and behavioral details of the compilation.
- Rsdoctor is a tool that can analyze the time-consuming and compilation process of the rspack builtin:swc-loader.

## 🔥 Features

- **Compilation Visualization**: Rsdoctor visualizes the compilation behavior and time consumption, making it easy to view build issues.

- **Multiple Analysis Capabilities**: Rsdoctor supports build artifact, build-time analysis, and anti-degradation capabilities:

  - Build artifact support for resource lists and module dependencies, etc.
  - Build-time analysis supports Loader, Plugin, and Resolver building process analysis, including: **Rspack's builtin:swc-loader**.
  - Build rules support duplicate package detection and ES Version Check, etc.

- **Support Custom Rules**: In addition to built-in build scan rules, Rsdoctor also supports users adding custom component scan rules based on the build data of Rsdoctor.

## Quick Start

In an Rspeedy-based project, you can enable Rsdoctor as follows:

```bash
# dev
RSDOCTOR=true rspeedy dev

# build
RSDOCTOR=true rspeedy build
```

After running the above commands, Rspeedy will automatically register the Rsdoctor plugin, and after the build is completed, it will open the build analysis page. For complete features, please refer to [Rsdoctor document](https://rsdoctor.dev/).

## Options

If you need to configure the [options](https://rsdoctor.dev/config/options/options#options) provided by the Rsdoctor plugin, use [`tools.rsdoctor`](/api/rspeedy/rspeedy.tools.rsdoctor.md).

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  tools: {
    rsdoctor: {
      disableClientServer: true,
    },
  },
});
```

## Use custom Rsdoctor version

1. Install the Rsdoctor plugin:

<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.



---
url: /versions.md
---

# Lynx versions

In 2025, Lynx plan to publish 5 stable releases. You can find Lynx [release schedule](/blog/lynx-open-source-roadmap-2025.md) here.

## Next version (unreleased)

Developers can check out the new features currently in development in this release.

<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" />



---
url: /react/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>



---
url: /react/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>



---
url: /react/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.



---
url: /react/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` | Web: `dist/Swiper.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/product_detail_assets.zip) to use in your projects.

## Direct Node Manipulation

Here's a product detail page example that includes a swiper and some product details. The `<Swiper>` accepts images and displays them in a row. Currently, it can't scroll - let's make it interactive.

**This is an example below:  swiper**

**Entry:** `src/SwiperEmpty, src/utils/pics.ts`
**Bundle:** `dist/SwiperEmpty.lynx.bundle` | Web: `dist/SwiperEmpty.web.bundle`

```tsx {10}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} />
    </Page>
  );
}

root.render(<App />);

```



To achieve this, we need to complete two tasks:

1. Listen to touch events
2. Update scroll position

### Listen to Touch Events

Let's start by listening to touch events to calculate the current scroll progress.

When a touch starts, we record the initial touch coordinates. This allows us to calculate the distance moved (represented by `delta`) when the finger moves.

```tsx title="index.tsx" "{4-6,8-10}"
function Swiper() {
  const touchStartXRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
  }

  return (
    <view
      class="swiper-container"
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
    >
      {/* ... */}
    </view>
  );
}
```

Next, we use `currentOffsetRef` to track the swiper component's offset, adding it to `delta` to get the final offset.

```tsx title="index.tsx" "{13}"
function Swiper() {
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
  }
}
```

### Updating Scroll Position

Once we get the offset, we can update the scroll position. Add an `updateSwiperOffset` function and call it when the finger moves.

```tsx title="index.tsx" "{9}"
function Swiper() {
  function updateSwiperOffset(offset: number) {
    // Update scroll position
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
    updateSwiperOffset(offset);
  }
}
```

Next, we use [Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md) to update the `transform` property, thereby updating the scroll position.

```tsx title="index.tsx" "{5-9,14}"
function Swiper() {
  const containerRef = useRef<NodesRef>(null);

  function updateSwiperOffset(offset: number) {
    containerRef.current
      ?.setNativeProps({
        style: {
          transform: `translateX(${offset}px)`,
        },
      })
      .exec();
  }

  return <view ref={containerRef}></view>;
}
```

**This is an example below:  swiper**

**Entry:** `src/UpdateOffset, src/utils/pics.ts`
**Bundle:** `dist/UpdateOffset.lynx.bundle` | Web: `dist/UpdateOffset.web.bundle`

```tsx
import "./styles.scss";
import { useRef } from "@lynx-js/react";
import type { NodesRef, TouchEvent } from "@lynx-js/types";
import { SwiperItem } from "./SwiperItem";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const containerRef = useRef<NodesRef>(null);
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function updateSwiperOffset(offset: number) {
    currentOffsetRef.current = offset;
    containerRef.current?.setNativeProps({
      transform: `translateX(${offset}px)`,
    }).exec();
  }

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;

    updateSwiperOffset(offset);
  }

  function handleTouchEnd(e: TouchEvent) {
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



Now the `<Swiper>` component can scroll with finger movements!

::: details Why not use state to update progress?
You might think of using `state` to update the progress, like this:

```tsx title="Swiper.tsx"
function Swiper() {
  const [offset, setOffset] = useState(0);

  return (
    <view style={{ transform: `translateX(${offset}px)` }}>{/* ... */}</view>
  );
}
```

However, in scenarios requiring frequent updates, this approach would cause constant component re-rendering, affecting performance. A better approach is to directly manipulate nodes, as shown in the example.

You can refer to [Direct Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to learn more.
:::

### Simplifying Code with Hooks

The `<Swiper>` component's code is getting complex. We can use hooks to encapsulate the logic into two parts, simplifying the component code and improving maintainability:

1. Encapsulate the [touch event listening](#listening-to-touch-events) code into `useOffset`, centralizing all scroll-related logic in this hook
2. Encapsulate the [scroll position update](#updating-scroll-position) code into `useUpdateSwiperStyle`, centralizing all `<Swiper>` component style update logic in this hook

```tsx title="Swiper.tsx"
function Swiper() {
  const { updateSwiperStyle, swiperContainerRef } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view
      class="swiper-container"
      ref={swiperContainerRef}
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
      bindtouchend={handleTouchEnd}
    >
      {/* ... */}
    </view>
  );
}
```

Finally, the code is more concise.

**This is an example below:  swiper**

**Entry:** `src/SwiperHooks, src/utils/pics.ts`
**Bundle:** `dist/SwiperHooks.lynx.bundle` | Web: `dist/SwiperHooks.web.bundle`

```tsx {13-16}
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



## Use Main Thread Script to Reduce Latency

You may have noticed that sometimes the scrolling doesn't feel smooth. This is because touch events occur in the **main thread**, while event listener code runs in the **background thread**, causing delayed touch event responses. This phenomenon is particularly noticeable on low-end devices.

We can use [Main Thread Script](/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



To achieve that, we need to migrate frequently triggered code to main thread script, including:

1. Event listener code
2. Node position update code

Let's modify both `useOffset` and `useUpdateSwiperStyle`.

### `useOffset`

Add the `main thread` identifier to `handleTouchStart` and `handleTouchMove` to convert them into **main thread functions**.

```tsx title="useOffset.ts"
function useOffset() {
  const touchStartXRef = useMainThreadRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    'main thread'
    ...
  }

  function handleTouchMove(e: TouchEvent) {
    'main thread'
    ...
  }
}
```

Convert `bindtouchstart` and `bindtouchmove` to `main-thread:bindtouchstart` and `main-thread:bindtouchmove` to listen to events in main thread script.

```tsx title="index.tsx"
<view
  main-thread:bindtouchstart={handleTouchStart}
  main-thread:bindtouchmove={handleTouchMove}
>
  {/* ... */}
</view>
```

### `useUpdateSwiperStyle`

Convert `useRef` to `useMainThreadRef`.

```tsx title="useUpdateSwiperStyle.ts" "{2}"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
   'main thread'
    ...
  }

  return {
    swiperContainerRef,
  }
}
```

Pass `swiperContainerRef` to `<view>` through the `main-thread:ref` attribute to access the node in the main thread.

```tsx title="index.tsx"
<view main-thread:ref={swiperContainerRef}>{/* ... */}</view>
```

The main thread node provides many capabilities, as shown in [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md). Here we call the `setStyleProperties` method to modify the `transform` property, updating the `<Swiper>` component's position.

```tsx title="useUpdateSwiperStyle.ts"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
    'main thread';
    swiperContainerRef.current?.setStyleProperties({
      transform: `translateX(${offset}px)`,
    });
  }
}
```

With this, we've completed the main thread script conversion. Now high-frequency functions run in the main thread, making the interaction smoother.

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



::: details Use Main Thread Script Sparingly
Only use main thread script when encountering response delay issues with frequently triggered events!

- Introducing main thread script increases code complexity because main thread script and background thread script run in isolated environments and need "special bridges" to communicate.

- Main thread script run high-frequency code in the main thread, increasing its burden. Overuse may cause main thread lag.

:::

## Communication Between Main Thread and Background Thread

Here's a progress indicator example that shows which page you're on when scrolling.

Currently, it only has styling but lacks progress update logic. We'll use this example to demonstrate how to enable communication between main thread and background thread:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorEmpty, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorEmpty.lynx.bundle` | Web: `dist/MTSIndicatorEmpty.web.bundle`

```tsx {33}
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



### Main Thread Calling Background Thread

The core of the progress indicator is the `<Indicator>` component, which accepts a `current` prop indicating the current page.

```tsx title="Swiper.tsx" "{7}"
function Swiper() {
  const [current, setCurrent] = useState(0);

  return (
    <view>
      {/* ... */}
      <Indicator current={current} />
    </view>
  );
}
```

Now we just need to update `current` when scrolling.

We add an `onIndexChange` callback to `useOffset` to update `current` during scrolling.

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      onIndexUpdate(index);
    }
  }
}
```

And pass `setCurrent` as the `onIndexUpdate` callback to `useOffset`.

```tsx title="Swiper.tsx" "{4}"
const [current, setCurrent] = useState(0);

const { handleTouchMove } = useOffset({
  onIndexUpdate: setCurrent,
});
```

This way, when scrolling past a page, `useOffset` will call `onIndexUpdate` to update `current`, thereby updating the progress indicator.

But wait, why is there an error?!

![Error](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/tutorial/Swiper/MTSIndicatorWrong.png)

:::info Main Thread and Background Thread Functions Need Special APIs to Call Each Other
Main thread script and background thread script run in separate runtimes. Functions in one runtime cannot directly call functions in another runtime. They need "special bridges" to communicate:

- From background to main thread: Use [`runOnMainThread`](/api/react/Function.runOnMainThread.md)
- From main thread to background: Use [`runOnBackground`](/api/react/Function.runOnBackground.md)

:::

`onIndexUpdate` is a background thread function. When called in a main thread function, we need to use `runOnBackground`

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }
}
```

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorCurrent, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorCurrent.lynx.bundle` | Web: `dist/MTSIndicatorCurrent.web.bundle`

```tsx
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
    onIndexUpdate: setCurrent,
    itemWidth,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



Now the progress indicator updates automatically as you scroll!

### Background Thread Calling Main Thread

A useful progress indicator should also support clicking to jump to the corresponding page. Let's add click-to-jump functionality to the `<Indicator>` component.

Add an `updateIndex` method in `useOffset` that uses `runOnMainThread` to call `updateOffset` to update the component position.

```tsx title="useOffset.ts" "{4}"
function useOffset({ itemWidth, onIndexUpdate }) {
  function updateIndex(index: number) {
    const offset = index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  return {
    updateIndex,
  };
}
```

Here's the complete code:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicator, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicator.lynx.bundle` | Web: `dist/MTSIndicator.web.bundle`

```ts
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function updateOffset(offset: number) {
    "main thread";
    currentOffsetRef.current = offset;
    onOffsetUpdate(offset);
    const index = Math.round(-offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



Great! Now the progress indicator supports click-to-jump functionality.

## Values Across Main Thread and Background Thread Script

In the following example, we've added a snap effect animation to the `<Swiper>` component. Currently, the snap effect animation isn't ideal, we can add some props to customize it.

**This is an example below:  swiper**

**Entry:** `src/EasingDefault, src/utils`
**Bundle:** `dist/EasingDefault.lynx.bundle` | Web: `dist/EasingDefault.web.bundle`

```ts {66-73}
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";
import { useAnimate } from "./useAnimate";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
  dataLength,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
  dataLength: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);
  const { animate, cancel: cancelAnimate } = useAnimate();
  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function calcNearestPage(offset: number) {
    "main thread";
    const nearestPage = Math.round(offset / itemWidth);
    return nearestPage * itemWidth;
  }

  function updateOffset(offset: number) {
    "main thread";

    const lowerBound = 0;
    const upperBound = -(dataLength - 1) * itemWidth;

    const realOffset = Math.min(lowerBound, Math.max(upperBound, offset));
    currentOffsetRef.current = realOffset;
    onOffsetUpdate(realOffset);
    const index = Math.round(-realOffset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
    cancelAnimate();
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: (offset) => {
        "main thread";
        updateOffset(offset);
      },
    });
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



We'll use this example to demonstrate value passing between main thread and background thread script.

### Main Thread Script Using Background Thread Script Values

First, we add a `duration` prop to the `<Swiper>` component to control the snap animation duration.

```tsx title="index.tsx"
<Swiper duration={300} />
```

Let's see how it works internally. When touch ends, `useOffset` calls the `animate` function to update the component position with animation effects. `animate` is a main thread function that accepts initial and target values and updates the component position according to the animation curve over the `duration` time.

```tsx title="useOffset.ts" {15-19}
function useOffset({
  duration,
}) {
  const currentOffsetRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    'main thread'
    // Update Component Offset
  }

  ...
  function handleTouchEnd() {
    'main thread'
    ...
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: updateOffset,
      duration,
    })
  }
}
```

Here, both `animate` and `handleTouchEnd` are main thread functions, and they can access the background thread value `duration`.

:::info Main Thread Functions Can Use Background Thread Values
Main thread script and background thread script run in separate runtimes and are isolated from each other.

However, to simplify main thread script development, Lynx automatically passes background thread values that main thread functions **depend on** to those functions, though this process has some limitations:

- The dependent background thread values must be serializable, so functions, `Promise`s, and other non-serializable values cannot be passed.
- Value passing only occurs during component `render`. If background thread values change after `render`, main thread functions won't be aware of these updates.

:::

### Background Thread Passing Main Thread Values

Next, we add a `main-thread:easing` prop to the `<Swiper>` component to allow users to customize the animation curve.

```tsx title="index.tsx" {6}
function easeInOut(x: number) {
  'main thread';
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
}

<Swiper main-thread:easing={easeInOut} />;
```

Inside the component, the main thread function `easeInOut` is passed to the background thread hook `useOffset`

```tsx title="Swiper.tsx" {2,6}
function Swiper({
  'main-thread:easing': MTEasing,
}) {
  ...
  const { handleTouchStart, ... } = useOffset({
    MTEasing,
  });
}
```

And in `useOffset`, it's passed to the main thread function `animate`.

```tsx title="useOffset.ts" {3,11}
function useOffset({
  duration,
  MTEasing,
}) {
  ...
  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    // ...
    animate({
      duration,
      easing: MTEasing,
    });
  }
}
```

:::info Main Thread Values Can Be Passed by Background Thread But Not Used
Main thread values, such as `MainThreadRef` and main thread functions, cannot be directly used by the background thread.

However, they can be passed by the background thread, such as being passed as `props` to components or as function parameters to other hooks or functions, and ultimately used in the main thread.
:::

:::details Add main-thread: Prefix for Props That Need Main Thread Functions
You may have noticed that when passing main thread functions or `MainThreadRef` as attributes, they need the `main-thread:` prefix, like `main-thread:ref` and `main-thread:bindtouchstart`.

By convention, when a prop expects a main thread function, it should have the `main-thread:` prefix, like `main-thread:easing`. We recommend following this convention for custom components too. This helps component users understand that the property requires a main thread function.

However, because variable names containing colons `:` are illegal in JavaScript, you need to rename these props when using them inside components.

```tsx title="Swiper.tsx"
function Swiper({ 'main-thread:easing': MTEasing }) {}
```

:::

Finally, we have a swiper with customizable animation curves.

**This is an example below:  swiper**

**Entry:** `src/Swiper, src/utils`
**Bundle:** `dist/Swiper.lynx.bundle` | Web: `dist/Swiper.web.bundle`

```tsx {15}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Summary

In this tutorial, we started with a simple `<Swiper>` component, gradually optimized its performance, and finally implemented a swiper with customizable animation curves.

We learned about:

- Using direct node manipulation to optimize performance
- Leveraging main thread script to enhance interaction experience
- Implementing communication between main thread and background thread
- Understanding value passing between main thread and background thread script



---
url: /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>



---
url: /rspeedy/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>



---
url: /rspeedy/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.



---
url: /rspeedy/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` | Web: `dist/Swiper.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/product_detail_assets.zip) to use in your projects.

## Direct Node Manipulation

Here's a product detail page example that includes a swiper and some product details. The `<Swiper>` accepts images and displays them in a row. Currently, it can't scroll - let's make it interactive.

**This is an example below:  swiper**

**Entry:** `src/SwiperEmpty, src/utils/pics.ts`
**Bundle:** `dist/SwiperEmpty.lynx.bundle` | Web: `dist/SwiperEmpty.web.bundle`

```tsx {10}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} />
    </Page>
  );
}

root.render(<App />);

```



To achieve this, we need to complete two tasks:

1. Listen to touch events
2. Update scroll position

### Listen to Touch Events

Let's start by listening to touch events to calculate the current scroll progress.

When a touch starts, we record the initial touch coordinates. This allows us to calculate the distance moved (represented by `delta`) when the finger moves.

```tsx title="index.tsx" "{4-6,8-10}"
function Swiper() {
  const touchStartXRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
  }

  return (
    <view
      class="swiper-container"
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
    >
      {/* ... */}
    </view>
  );
}
```

Next, we use `currentOffsetRef` to track the swiper component's offset, adding it to `delta` to get the final offset.

```tsx title="index.tsx" "{13}"
function Swiper() {
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
  }
}
```

### Updating Scroll Position

Once we get the offset, we can update the scroll position. Add an `updateSwiperOffset` function and call it when the finger moves.

```tsx title="index.tsx" "{9}"
function Swiper() {
  function updateSwiperOffset(offset: number) {
    // Update scroll position
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
    updateSwiperOffset(offset);
  }
}
```

Next, we use [Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md) to update the `transform` property, thereby updating the scroll position.

```tsx title="index.tsx" "{5-9,14}"
function Swiper() {
  const containerRef = useRef<NodesRef>(null);

  function updateSwiperOffset(offset: number) {
    containerRef.current
      ?.setNativeProps({
        style: {
          transform: `translateX(${offset}px)`,
        },
      })
      .exec();
  }

  return <view ref={containerRef}></view>;
}
```

**This is an example below:  swiper**

**Entry:** `src/UpdateOffset, src/utils/pics.ts`
**Bundle:** `dist/UpdateOffset.lynx.bundle` | Web: `dist/UpdateOffset.web.bundle`

```tsx
import "./styles.scss";
import { useRef } from "@lynx-js/react";
import type { NodesRef, TouchEvent } from "@lynx-js/types";
import { SwiperItem } from "./SwiperItem";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const containerRef = useRef<NodesRef>(null);
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function updateSwiperOffset(offset: number) {
    currentOffsetRef.current = offset;
    containerRef.current?.setNativeProps({
      transform: `translateX(${offset}px)`,
    }).exec();
  }

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;

    updateSwiperOffset(offset);
  }

  function handleTouchEnd(e: TouchEvent) {
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



Now the `<Swiper>` component can scroll with finger movements!

::: details Why not use state to update progress?
You might think of using `state` to update the progress, like this:

```tsx title="Swiper.tsx"
function Swiper() {
  const [offset, setOffset] = useState(0);

  return (
    <view style={{ transform: `translateX(${offset}px)` }}>{/* ... */}</view>
  );
}
```

However, in scenarios requiring frequent updates, this approach would cause constant component re-rendering, affecting performance. A better approach is to directly manipulate nodes, as shown in the example.

You can refer to [Direct Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to learn more.
:::

### Simplifying Code with Hooks

The `<Swiper>` component's code is getting complex. We can use hooks to encapsulate the logic into two parts, simplifying the component code and improving maintainability:

1. Encapsulate the [touch event listening](#listening-to-touch-events) code into `useOffset`, centralizing all scroll-related logic in this hook
2. Encapsulate the [scroll position update](#updating-scroll-position) code into `useUpdateSwiperStyle`, centralizing all `<Swiper>` component style update logic in this hook

```tsx title="Swiper.tsx"
function Swiper() {
  const { updateSwiperStyle, swiperContainerRef } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view
      class="swiper-container"
      ref={swiperContainerRef}
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
      bindtouchend={handleTouchEnd}
    >
      {/* ... */}
    </view>
  );
}
```

Finally, the code is more concise.

**This is an example below:  swiper**

**Entry:** `src/SwiperHooks, src/utils/pics.ts`
**Bundle:** `dist/SwiperHooks.lynx.bundle` | Web: `dist/SwiperHooks.web.bundle`

```tsx {13-16}
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



## Use Main Thread Script to Reduce Latency

You may have noticed that sometimes the scrolling doesn't feel smooth. This is because touch events occur in the **main thread**, while event listener code runs in the **background thread**, causing delayed touch event responses. This phenomenon is particularly noticeable on low-end devices.

We can use [Main Thread Script](/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



To achieve that, we need to migrate frequently triggered code to main thread script, including:

1. Event listener code
2. Node position update code

Let's modify both `useOffset` and `useUpdateSwiperStyle`.

### `useOffset`

Add the `main thread` identifier to `handleTouchStart` and `handleTouchMove` to convert them into **main thread functions**.

```tsx title="useOffset.ts"
function useOffset() {
  const touchStartXRef = useMainThreadRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    'main thread'
    ...
  }

  function handleTouchMove(e: TouchEvent) {
    'main thread'
    ...
  }
}
```

Convert `bindtouchstart` and `bindtouchmove` to `main-thread:bindtouchstart` and `main-thread:bindtouchmove` to listen to events in main thread script.

```tsx title="index.tsx"
<view
  main-thread:bindtouchstart={handleTouchStart}
  main-thread:bindtouchmove={handleTouchMove}
>
  {/* ... */}
</view>
```

### `useUpdateSwiperStyle`

Convert `useRef` to `useMainThreadRef`.

```tsx title="useUpdateSwiperStyle.ts" "{2}"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
   'main thread'
    ...
  }

  return {
    swiperContainerRef,
  }
}
```

Pass `swiperContainerRef` to `<view>` through the `main-thread:ref` attribute to access the node in the main thread.

```tsx title="index.tsx"
<view main-thread:ref={swiperContainerRef}>{/* ... */}</view>
```

The main thread node provides many capabilities, as shown in [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md). Here we call the `setStyleProperties` method to modify the `transform` property, updating the `<Swiper>` component's position.

```tsx title="useUpdateSwiperStyle.ts"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
    'main thread';
    swiperContainerRef.current?.setStyleProperties({
      transform: `translateX(${offset}px)`,
    });
  }
}
```

With this, we've completed the main thread script conversion. Now high-frequency functions run in the main thread, making the interaction smoother.

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



::: details Use Main Thread Script Sparingly
Only use main thread script when encountering response delay issues with frequently triggered events!

- Introducing main thread script increases code complexity because main thread script and background thread script run in isolated environments and need "special bridges" to communicate.

- Main thread script run high-frequency code in the main thread, increasing its burden. Overuse may cause main thread lag.

:::

## Communication Between Main Thread and Background Thread

Here's a progress indicator example that shows which page you're on when scrolling.

Currently, it only has styling but lacks progress update logic. We'll use this example to demonstrate how to enable communication between main thread and background thread:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorEmpty, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorEmpty.lynx.bundle` | Web: `dist/MTSIndicatorEmpty.web.bundle`

```tsx {33}
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



### Main Thread Calling Background Thread

The core of the progress indicator is the `<Indicator>` component, which accepts a `current` prop indicating the current page.

```tsx title="Swiper.tsx" "{7}"
function Swiper() {
  const [current, setCurrent] = useState(0);

  return (
    <view>
      {/* ... */}
      <Indicator current={current} />
    </view>
  );
}
```

Now we just need to update `current` when scrolling.

We add an `onIndexChange` callback to `useOffset` to update `current` during scrolling.

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      onIndexUpdate(index);
    }
  }
}
```

And pass `setCurrent` as the `onIndexUpdate` callback to `useOffset`.

```tsx title="Swiper.tsx" "{4}"
const [current, setCurrent] = useState(0);

const { handleTouchMove } = useOffset({
  onIndexUpdate: setCurrent,
});
```

This way, when scrolling past a page, `useOffset` will call `onIndexUpdate` to update `current`, thereby updating the progress indicator.

But wait, why is there an error?!

![Error](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/tutorial/Swiper/MTSIndicatorWrong.png)

:::info Main Thread and Background Thread Functions Need Special APIs to Call Each Other
Main thread script and background thread script run in separate runtimes. Functions in one runtime cannot directly call functions in another runtime. They need "special bridges" to communicate:

- From background to main thread: Use [`runOnMainThread`](/api/react/Function.runOnMainThread.md)
- From main thread to background: Use [`runOnBackground`](/api/react/Function.runOnBackground.md)

:::

`onIndexUpdate` is a background thread function. When called in a main thread function, we need to use `runOnBackground`

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }
}
```

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorCurrent, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorCurrent.lynx.bundle` | Web: `dist/MTSIndicatorCurrent.web.bundle`

```tsx
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
    onIndexUpdate: setCurrent,
    itemWidth,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



Now the progress indicator updates automatically as you scroll!

### Background Thread Calling Main Thread

A useful progress indicator should also support clicking to jump to the corresponding page. Let's add click-to-jump functionality to the `<Indicator>` component.

Add an `updateIndex` method in `useOffset` that uses `runOnMainThread` to call `updateOffset` to update the component position.

```tsx title="useOffset.ts" "{4}"
function useOffset({ itemWidth, onIndexUpdate }) {
  function updateIndex(index: number) {
    const offset = index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  return {
    updateIndex,
  };
}
```

Here's the complete code:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicator, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicator.lynx.bundle` | Web: `dist/MTSIndicator.web.bundle`

```ts
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function updateOffset(offset: number) {
    "main thread";
    currentOffsetRef.current = offset;
    onOffsetUpdate(offset);
    const index = Math.round(-offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



Great! Now the progress indicator supports click-to-jump functionality.

## Values Across Main Thread and Background Thread Script

In the following example, we've added a snap effect animation to the `<Swiper>` component. Currently, the snap effect animation isn't ideal, we can add some props to customize it.

**This is an example below:  swiper**

**Entry:** `src/EasingDefault, src/utils`
**Bundle:** `dist/EasingDefault.lynx.bundle` | Web: `dist/EasingDefault.web.bundle`

```ts {66-73}
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";
import { useAnimate } from "./useAnimate";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
  dataLength,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
  dataLength: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);
  const { animate, cancel: cancelAnimate } = useAnimate();
  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function calcNearestPage(offset: number) {
    "main thread";
    const nearestPage = Math.round(offset / itemWidth);
    return nearestPage * itemWidth;
  }

  function updateOffset(offset: number) {
    "main thread";

    const lowerBound = 0;
    const upperBound = -(dataLength - 1) * itemWidth;

    const realOffset = Math.min(lowerBound, Math.max(upperBound, offset));
    currentOffsetRef.current = realOffset;
    onOffsetUpdate(realOffset);
    const index = Math.round(-realOffset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
    cancelAnimate();
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: (offset) => {
        "main thread";
        updateOffset(offset);
      },
    });
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



We'll use this example to demonstrate value passing between main thread and background thread script.

### Main Thread Script Using Background Thread Script Values

First, we add a `duration` prop to the `<Swiper>` component to control the snap animation duration.

```tsx title="index.tsx"
<Swiper duration={300} />
```

Let's see how it works internally. When touch ends, `useOffset` calls the `animate` function to update the component position with animation effects. `animate` is a main thread function that accepts initial and target values and updates the component position according to the animation curve over the `duration` time.

```tsx title="useOffset.ts" {15-19}
function useOffset({
  duration,
}) {
  const currentOffsetRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    'main thread'
    // Update Component Offset
  }

  ...
  function handleTouchEnd() {
    'main thread'
    ...
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: updateOffset,
      duration,
    })
  }
}
```

Here, both `animate` and `handleTouchEnd` are main thread functions, and they can access the background thread value `duration`.

:::info Main Thread Functions Can Use Background Thread Values
Main thread script and background thread script run in separate runtimes and are isolated from each other.

However, to simplify main thread script development, Lynx automatically passes background thread values that main thread functions **depend on** to those functions, though this process has some limitations:

- The dependent background thread values must be serializable, so functions, `Promise`s, and other non-serializable values cannot be passed.
- Value passing only occurs during component `render`. If background thread values change after `render`, main thread functions won't be aware of these updates.

:::

### Background Thread Passing Main Thread Values

Next, we add a `main-thread:easing` prop to the `<Swiper>` component to allow users to customize the animation curve.

```tsx title="index.tsx" {6}
function easeInOut(x: number) {
  'main thread';
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
}

<Swiper main-thread:easing={easeInOut} />;
```

Inside the component, the main thread function `easeInOut` is passed to the background thread hook `useOffset`

```tsx title="Swiper.tsx" {2,6}
function Swiper({
  'main-thread:easing': MTEasing,
}) {
  ...
  const { handleTouchStart, ... } = useOffset({
    MTEasing,
  });
}
```

And in `useOffset`, it's passed to the main thread function `animate`.

```tsx title="useOffset.ts" {3,11}
function useOffset({
  duration,
  MTEasing,
}) {
  ...
  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    // ...
    animate({
      duration,
      easing: MTEasing,
    });
  }
}
```

:::info Main Thread Values Can Be Passed by Background Thread But Not Used
Main thread values, such as `MainThreadRef` and main thread functions, cannot be directly used by the background thread.

However, they can be passed by the background thread, such as being passed as `props` to components or as function parameters to other hooks or functions, and ultimately used in the main thread.
:::

:::details Add main-thread: Prefix for Props That Need Main Thread Functions
You may have noticed that when passing main thread functions or `MainThreadRef` as attributes, they need the `main-thread:` prefix, like `main-thread:ref` and `main-thread:bindtouchstart`.

By convention, when a prop expects a main thread function, it should have the `main-thread:` prefix, like `main-thread:easing`. We recommend following this convention for custom components too. This helps component users understand that the property requires a main thread function.

However, because variable names containing colons `:` are illegal in JavaScript, you need to rename these props when using them inside components.

```tsx title="Swiper.tsx"
function Swiper({ 'main-thread:easing': MTEasing }) {}
```

:::

Finally, we have a swiper with customizable animation curves.

**This is an example below:  swiper**

**Entry:** `src/Swiper, src/utils`
**Bundle:** `dist/Swiper.lynx.bundle` | Web: `dist/Swiper.web.bundle`

```tsx {15}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Summary

In this tutorial, we started with a simple `<Swiper>` component, gradually optimized its performance, and finally implemented a swiper with customizable animation curves.

We learned about:

- Using direct node manipulation to optimize performance
- Leveraging main thread script to enhance interaction experience
- Implementing communication between main thread and background thread
- Understanding value passing between main thread and background thread script



---
url: /ai/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>



---
url: /ai/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>



---
url: /ai/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.



---
url: /ai/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` | Web: `dist/Swiper.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/product_detail_assets.zip) to use in your projects.

## Direct Node Manipulation

Here's a product detail page example that includes a swiper and some product details. The `<Swiper>` accepts images and displays them in a row. Currently, it can't scroll - let's make it interactive.

**This is an example below:  swiper**

**Entry:** `src/SwiperEmpty, src/utils/pics.ts`
**Bundle:** `dist/SwiperEmpty.lynx.bundle` | Web: `dist/SwiperEmpty.web.bundle`

```tsx {10}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} />
    </Page>
  );
}

root.render(<App />);

```



To achieve this, we need to complete two tasks:

1. Listen to touch events
2. Update scroll position

### Listen to Touch Events

Let's start by listening to touch events to calculate the current scroll progress.

When a touch starts, we record the initial touch coordinates. This allows us to calculate the distance moved (represented by `delta`) when the finger moves.

```tsx title="index.tsx" "{4-6,8-10}"
function Swiper() {
  const touchStartXRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
  }

  return (
    <view
      class="swiper-container"
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
    >
      {/* ... */}
    </view>
  );
}
```

Next, we use `currentOffsetRef` to track the swiper component's offset, adding it to `delta` to get the final offset.

```tsx title="index.tsx" "{13}"
function Swiper() {
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
  }
}
```

### Updating Scroll Position

Once we get the offset, we can update the scroll position. Add an `updateSwiperOffset` function and call it when the finger moves.

```tsx title="index.tsx" "{9}"
function Swiper() {
  function updateSwiperOffset(offset: number) {
    // Update scroll position
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
    updateSwiperOffset(offset);
  }
}
```

Next, we use [Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md) to update the `transform` property, thereby updating the scroll position.

```tsx title="index.tsx" "{5-9,14}"
function Swiper() {
  const containerRef = useRef<NodesRef>(null);

  function updateSwiperOffset(offset: number) {
    containerRef.current
      ?.setNativeProps({
        style: {
          transform: `translateX(${offset}px)`,
        },
      })
      .exec();
  }

  return <view ref={containerRef}></view>;
}
```

**This is an example below:  swiper**

**Entry:** `src/UpdateOffset, src/utils/pics.ts`
**Bundle:** `dist/UpdateOffset.lynx.bundle` | Web: `dist/UpdateOffset.web.bundle`

```tsx
import "./styles.scss";
import { useRef } from "@lynx-js/react";
import type { NodesRef, TouchEvent } from "@lynx-js/types";
import { SwiperItem } from "./SwiperItem";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const containerRef = useRef<NodesRef>(null);
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function updateSwiperOffset(offset: number) {
    currentOffsetRef.current = offset;
    containerRef.current?.setNativeProps({
      transform: `translateX(${offset}px)`,
    }).exec();
  }

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;

    updateSwiperOffset(offset);
  }

  function handleTouchEnd(e: TouchEvent) {
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



Now the `<Swiper>` component can scroll with finger movements!

::: details Why not use state to update progress?
You might think of using `state` to update the progress, like this:

```tsx title="Swiper.tsx"
function Swiper() {
  const [offset, setOffset] = useState(0);

  return (
    <view style={{ transform: `translateX(${offset}px)` }}>{/* ... */}</view>
  );
}
```

However, in scenarios requiring frequent updates, this approach would cause constant component re-rendering, affecting performance. A better approach is to directly manipulate nodes, as shown in the example.

You can refer to [Direct Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to learn more.
:::

### Simplifying Code with Hooks

The `<Swiper>` component's code is getting complex. We can use hooks to encapsulate the logic into two parts, simplifying the component code and improving maintainability:

1. Encapsulate the [touch event listening](#listening-to-touch-events) code into `useOffset`, centralizing all scroll-related logic in this hook
2. Encapsulate the [scroll position update](#updating-scroll-position) code into `useUpdateSwiperStyle`, centralizing all `<Swiper>` component style update logic in this hook

```tsx title="Swiper.tsx"
function Swiper() {
  const { updateSwiperStyle, swiperContainerRef } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view
      class="swiper-container"
      ref={swiperContainerRef}
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
      bindtouchend={handleTouchEnd}
    >
      {/* ... */}
    </view>
  );
}
```

Finally, the code is more concise.

**This is an example below:  swiper**

**Entry:** `src/SwiperHooks, src/utils/pics.ts`
**Bundle:** `dist/SwiperHooks.lynx.bundle` | Web: `dist/SwiperHooks.web.bundle`

```tsx {13-16}
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



## Use Main Thread Script to Reduce Latency

You may have noticed that sometimes the scrolling doesn't feel smooth. This is because touch events occur in the **main thread**, while event listener code runs in the **background thread**, causing delayed touch event responses. This phenomenon is particularly noticeable on low-end devices.

We can use [Main Thread Script](/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



To achieve that, we need to migrate frequently triggered code to main thread script, including:

1. Event listener code
2. Node position update code

Let's modify both `useOffset` and `useUpdateSwiperStyle`.

### `useOffset`

Add the `main thread` identifier to `handleTouchStart` and `handleTouchMove` to convert them into **main thread functions**.

```tsx title="useOffset.ts"
function useOffset() {
  const touchStartXRef = useMainThreadRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    'main thread'
    ...
  }

  function handleTouchMove(e: TouchEvent) {
    'main thread'
    ...
  }
}
```

Convert `bindtouchstart` and `bindtouchmove` to `main-thread:bindtouchstart` and `main-thread:bindtouchmove` to listen to events in main thread script.

```tsx title="index.tsx"
<view
  main-thread:bindtouchstart={handleTouchStart}
  main-thread:bindtouchmove={handleTouchMove}
>
  {/* ... */}
</view>
```

### `useUpdateSwiperStyle`

Convert `useRef` to `useMainThreadRef`.

```tsx title="useUpdateSwiperStyle.ts" "{2}"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
   'main thread'
    ...
  }

  return {
    swiperContainerRef,
  }
}
```

Pass `swiperContainerRef` to `<view>` through the `main-thread:ref` attribute to access the node in the main thread.

```tsx title="index.tsx"
<view main-thread:ref={swiperContainerRef}>{/* ... */}</view>
```

The main thread node provides many capabilities, as shown in [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md). Here we call the `setStyleProperties` method to modify the `transform` property, updating the `<Swiper>` component's position.

```tsx title="useUpdateSwiperStyle.ts"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
    'main thread';
    swiperContainerRef.current?.setStyleProperties({
      transform: `translateX(${offset}px)`,
    });
  }
}
```

With this, we've completed the main thread script conversion. Now high-frequency functions run in the main thread, making the interaction smoother.

**This is an example below:  swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



::: details Use Main Thread Script Sparingly
Only use main thread script when encountering response delay issues with frequently triggered events!

- Introducing main thread script increases code complexity because main thread script and background thread script run in isolated environments and need "special bridges" to communicate.

- Main thread script run high-frequency code in the main thread, increasing its burden. Overuse may cause main thread lag.

:::

## Communication Between Main Thread and Background Thread

Here's a progress indicator example that shows which page you're on when scrolling.

Currently, it only has styling but lacks progress update logic. We'll use this example to demonstrate how to enable communication between main thread and background thread:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorEmpty, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorEmpty.lynx.bundle` | Web: `dist/MTSIndicatorEmpty.web.bundle`

```tsx {33}
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



### Main Thread Calling Background Thread

The core of the progress indicator is the `<Indicator>` component, which accepts a `current` prop indicating the current page.

```tsx title="Swiper.tsx" "{7}"
function Swiper() {
  const [current, setCurrent] = useState(0);

  return (
    <view>
      {/* ... */}
      <Indicator current={current} />
    </view>
  );
}
```

Now we just need to update `current` when scrolling.

We add an `onIndexChange` callback to `useOffset` to update `current` during scrolling.

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      onIndexUpdate(index);
    }
  }
}
```

And pass `setCurrent` as the `onIndexUpdate` callback to `useOffset`.

```tsx title="Swiper.tsx" "{4}"
const [current, setCurrent] = useState(0);

const { handleTouchMove } = useOffset({
  onIndexUpdate: setCurrent,
});
```

This way, when scrolling past a page, `useOffset` will call `onIndexUpdate` to update `current`, thereby updating the progress indicator.

But wait, why is there an error?!

![Error](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/tutorial/Swiper/MTSIndicatorWrong.png)

:::info Main Thread and Background Thread Functions Need Special APIs to Call Each Other
Main thread script and background thread script run in separate runtimes. Functions in one runtime cannot directly call functions in another runtime. They need "special bridges" to communicate:

- From background to main thread: Use [`runOnMainThread`](/api/react/Function.runOnMainThread.md)
- From main thread to background: Use [`runOnBackground`](/api/react/Function.runOnBackground.md)

:::

`onIndexUpdate` is a background thread function. When called in a main thread function, we need to use `runOnBackground`

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }
}
```

**This is an example below:  swiper**

**Entry:** `src/MTSIndicatorCurrent, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorCurrent.lynx.bundle` | Web: `dist/MTSIndicatorCurrent.web.bundle`

```tsx
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
    onIndexUpdate: setCurrent,
    itemWidth,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



Now the progress indicator updates automatically as you scroll!

### Background Thread Calling Main Thread

A useful progress indicator should also support clicking to jump to the corresponding page. Let's add click-to-jump functionality to the `<Indicator>` component.

Add an `updateIndex` method in `useOffset` that uses `runOnMainThread` to call `updateOffset` to update the component position.

```tsx title="useOffset.ts" "{4}"
function useOffset({ itemWidth, onIndexUpdate }) {
  function updateIndex(index: number) {
    const offset = index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  return {
    updateIndex,
  };
}
```

Here's the complete code:

**This is an example below:  swiper**

**Entry:** `src/MTSIndicator, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicator.lynx.bundle` | Web: `dist/MTSIndicator.web.bundle`

```ts
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function updateOffset(offset: number) {
    "main thread";
    currentOffsetRef.current = offset;
    onOffsetUpdate(offset);
    const index = Math.round(-offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



Great! Now the progress indicator supports click-to-jump functionality.

## Values Across Main Thread and Background Thread Script

In the following example, we've added a snap effect animation to the `<Swiper>` component. Currently, the snap effect animation isn't ideal, we can add some props to customize it.

**This is an example below:  swiper**

**Entry:** `src/EasingDefault, src/utils`
**Bundle:** `dist/EasingDefault.lynx.bundle` | Web: `dist/EasingDefault.web.bundle`

```ts {66-73}
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";
import { useAnimate } from "./useAnimate";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
  dataLength,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
  dataLength: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);
  const { animate, cancel: cancelAnimate } = useAnimate();
  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function calcNearestPage(offset: number) {
    "main thread";
    const nearestPage = Math.round(offset / itemWidth);
    return nearestPage * itemWidth;
  }

  function updateOffset(offset: number) {
    "main thread";

    const lowerBound = 0;
    const upperBound = -(dataLength - 1) * itemWidth;

    const realOffset = Math.min(lowerBound, Math.max(upperBound, offset));
    currentOffsetRef.current = realOffset;
    onOffsetUpdate(realOffset);
    const index = Math.round(-realOffset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
    cancelAnimate();
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: (offset) => {
        "main thread";
        updateOffset(offset);
      },
    });
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



We'll use this example to demonstrate value passing between main thread and background thread script.

### Main Thread Script Using Background Thread Script Values

First, we add a `duration` prop to the `<Swiper>` component to control the snap animation duration.

```tsx title="index.tsx"
<Swiper duration={300} />
```

Let's see how it works internally. When touch ends, `useOffset` calls the `animate` function to update the component position with animation effects. `animate` is a main thread function that accepts initial and target values and updates the component position according to the animation curve over the `duration` time.

```tsx title="useOffset.ts" {15-19}
function useOffset({
  duration,
}) {
  const currentOffsetRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    'main thread'
    // Update Component Offset
  }

  ...
  function handleTouchEnd() {
    'main thread'
    ...
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: updateOffset,
      duration,
    })
  }
}
```

Here, both `animate` and `handleTouchEnd` are main thread functions, and they can access the background thread value `duration`.

:::info Main Thread Functions Can Use Background Thread Values
Main thread script and background thread script run in separate runtimes and are isolated from each other.

However, to simplify main thread script development, Lynx automatically passes background thread values that main thread functions **depend on** to those functions, though this process has some limitations:

- The dependent background thread values must be serializable, so functions, `Promise`s, and other non-serializable values cannot be passed.
- Value passing only occurs during component `render`. If background thread values change after `render`, main thread functions won't be aware of these updates.

:::

### Background Thread Passing Main Thread Values

Next, we add a `main-thread:easing` prop to the `<Swiper>` component to allow users to customize the animation curve.

```tsx title="index.tsx" {6}
function easeInOut(x: number) {
  'main thread';
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
}

<Swiper main-thread:easing={easeInOut} />;
```

Inside the component, the main thread function `easeInOut` is passed to the background thread hook `useOffset`

```tsx title="Swiper.tsx" {2,6}
function Swiper({
  'main-thread:easing': MTEasing,
}) {
  ...
  const { handleTouchStart, ... } = useOffset({
    MTEasing,
  });
}
```

And in `useOffset`, it's passed to the main thread function `animate`.

```tsx title="useOffset.ts" {3,11}
function useOffset({
  duration,
  MTEasing,
}) {
  ...
  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    // ...
    animate({
      duration,
      easing: MTEasing,
    });
  }
}
```

:::info Main Thread Values Can Be Passed by Background Thread But Not Used
Main thread values, such as `MainThreadRef` and main thread functions, cannot be directly used by the background thread.

However, they can be passed by the background thread, such as being passed as `props` to components or as function parameters to other hooks or functions, and ultimately used in the main thread.
:::

:::details Add main-thread: Prefix for Props That Need Main Thread Functions
You may have noticed that when passing main thread functions or `MainThreadRef` as attributes, they need the `main-thread:` prefix, like `main-thread:ref` and `main-thread:bindtouchstart`.

By convention, when a prop expects a main thread function, it should have the `main-thread:` prefix, like `main-thread:easing`. We recommend following this convention for custom components too. This helps component users understand that the property requires a main thread function.

However, because variable names containing colons `:` are illegal in JavaScript, you need to rename these props when using them inside components.

```tsx title="Swiper.tsx"
function Swiper({ 'main-thread:easing': MTEasing }) {}
```

:::

Finally, we have a swiper with customizable animation curves.

**This is an example below:  swiper**

**Entry:** `src/Swiper, src/utils`
**Bundle:** `dist/Swiper.lynx.bundle` | Web: `dist/Swiper.web.bundle`

```tsx {15}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Summary

In this tutorial, we started with a simple `<Swiper>` component, gradually optimized its performance, and finally implemented a swiper with customizable animation curves.

We learned about:

- Using direct node manipulation to optimize performance
- Leveraging main thread script to enhance interaction experience
- Implementing communication between main thread and background thread
- Understanding value passing between main thread and background thread script