---
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/interaction/storage.md
---




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

> The switch setting page is written in Lynx, and the DevTool component has already packaged the page.

Code example for integrating the devtool switch page:

```objective-c
#import <Lynx/LynxView.h>

#import "DebugSettingViewController.h"
#import "DemoLynxProvider.h"

@implementation DebugSettingViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
    builder.config = [[LynxConfig alloc] initWithProvider:[[DemoLynxProvider alloc] init]];
    builder.screenSize = self.view.frame.size;
    builder.fontScale = 1.0;
  }];

  lynxView.preferredLayoutWidth = self.view.frame.size.width;
  lynxView.preferredLayoutHeight = self.view.frame.size.height;
  lynxView.layoutWidthMode = LynxViewSizeModeExact;
  lynxView.layoutHeightMode = LynxViewSizeModeExact;

  [self.view addSubview:lynxView];

  NSString *bundlePath = [[NSBundle mainBundle] pathForResource:@"LynxDebugResources" ofType: @"bundle"];
  NSData *templateData = [[NSData alloc] initWithContentsOfFile:[bundlePath stringByAppendingString:@"/switchPage/devtoolSwitch.lynx.bundle"]];
  [lynxView loadTemplate:templateData withURL:@"devtool_switch/switchPage/devtoolSwitch.lynx.bundle"];
}

@end
```

```swift
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")
  }
}
```

> The switch setting page is written in Lynx, and the DevTool component has already packaged the page.

Code example for integrating the devtool switch page:

```java
public class SwitchActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);
        byte[] array = null;
        try {
            InputStream inputStream = this.getAssets().open("devtool_switch/switchPage/devtoolSwitch.lynx.bundle");
            array = readBytes(inputStream);
            lynxView.renderTemplateWithBaseUrl(array, TemplateData.empty(), "devtool_switch/switchPage/devtoolSwitch.lynx.bundle");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    private LynxView buildLynxView() {
        LynxViewBuilder viewBuilder = new LynxViewBuilder();
        viewBuilder.setTemplateProvider(new DemoTemplateProvider());
        return viewBuilder.build(this);
    }

    private byte[] readBytes(InputStream inputStream) throws IOException {
        byte[] buffer = new byte[1024];
        int bytesRead;
        ByteArrayOutputStream output = new ByteArrayOutputStream();
        while ((bytesRead = inputStream.read(buffer)) != -1) {
            output.write(buffer, 0, bytesRead);
        }
        return output.toByteArray();
    }

}

```

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

You can also customize the page according to your needs, making the configuration of DevTool more diverse.



---
url: /guide/start/integrate-lynx-devtool.md
---



# Integrating Lynx DevTool

When encountering issues during Lynx page development, you can use [DevTool](/guide/debugging/lynx-devtool.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.
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/release/3.1).

:::

### 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.2.0-rc.0', :subspecs => [
      'Devtool',
  ]
  pod 'LynxDevtool', '3.2.0-rc.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/debugging/handle-errors.md).

- When debugging Lynx pages with the DevTool Desktop, both `Lynx Debug` and
  `Lynx DevTool` need be enabled
- LogBox helps you quickly identify and diagnose issues

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

```objective-c title=AppDelegate.m {5-10}
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // ...
  // Enable Lynx Debug
  lynxEnv.lynxDebugEnabled = YES;
  // Enable Lynx DevTool
  lynxEnv.devtoolEnabled = YES;
  // Enable Lynx LogBox
  lynxEnv.logBoxEnabled = YES;
  return YES;
}
```

```swift title=AppDelegate.swift {5-10}
class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...
    // Enable Lynx Debug
    lynxEnv.lynxDebugEnabled = true
    // Enable Lynx DevTool
    lynxEnv.devtoolEnabled = true
    // Enable Lynx LogBox
    lynxEnv.logBoxEnabled = true
    return true
  }
}
```

:::info
In addition to the three switches introduced earlier, there are more switches that can help you control the behavior of DevTool. Please refer to the [Lynx DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch).
:::

### Adding Dependencies

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

```groovy
// Ensure Lynx DevTool version matches the Lynx version when integrating
dependencies {
  implementation "org.lynxsdk.lynx:lynx-devtool:3.2.0-rc.0"
  implementation "org.lynxsdk.lynx:lynx-service-devtool:3.2.0-rc.0"
}
```

```kotlin
// Ensure Lynx DevTool version matches the Lynx version when integrating
dependencies {
  implementation ("org.lynxsdk.lynx:lynx-devtool:3.2.0-rc.0")
  implementation ("org.lynxsdk.lynx:lynx-service-devtool:3.2.0-rc.0")
}
```

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

### Registering DevTool Service

```java title=YourApplication.java {3-4}
private void initLynxService() {
  // ...
  // register DevTool service
  LynxServiceCenter.inst().registerService(LynxDevToolService.INSTANCE);
}

```

```kotlin title=YourApplication.kt {3-4}
private fun initLynxService() {
  // ...
  // register DevTool service
  LynxServiceCenter.inst().registerService(LynxDevToolService)
}
```

### 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/debugging/handle-errors.md).

- When debugging Lynx pages with the DevTool Desktop, both `Lynx Debug` and
  `Lynx DevTool` switches need be enabled
- LogBox helps you quickly identify and diagnose issues

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

```java title=YourApplication.java {3-8}
private void initLynxEnv() {
  LynxEnv.inst().init(this, null, null, null);
  // Enable Lynx Debug
  LynxEnv.inst().enableLynxDebug(true);
  // Enable Lynx DevTool
  LynxEnv.inst().enableDevtool(true);
  // Enable Lynx LogBox
  LynxEnv.inst().enableLogBox(true);
}

```

```kotlin title=YourApplication.kt {3-8}
private fun initLynxEnv() {
  LynxEnv.inst().init(this, null, null, null)
  // Enable Lynx Debug
  LynxEnv.inst().enableLynxDebug(true)
  // Enable Lynx DevTool
  LynxEnv.inst().enableDevtool(true)
  // Enable Lynx LogBox
  LynxEnv.inst().enableLogBox(true)
}
```

:::info
In addition to the three switches introduced earlier, there are more that can help you control the behavior of DevTool. Please refer to the [DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch).
:::

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

## Next Step



---
url: /guide/start/integrate-with-existing-apps.md
---

import { PlatformTabs } from '@lynx';
import * as NextSteps from '@lynx/NextSteps';





# 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 hashKey="platform">
<PlatformTabs.Tab platform="ios">
### Integrate Lynx with Existing Apps (iOS)

import { Info, CodeFold } from '@lynx';
import { Steps } from '@theme';
import { Tab, Tabs } from 'rspress/theme';

<Info title="Lynx for iOS">
  - This article assumes that you are familiar with the basic concepts of native iOS application development.
  - You can refer to the project: [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/release/3.1) for all the code mentioned below.
</Info>

## 1. Dependency configuration

Using [Cocoapods](https://cocoapods.org/) can easily integrate Lynx into your application

<Info title="Recommended Versions">

- Cocoapods: >= 1.11.3
- Ruby: >= 2.6.10

</Info>

<Steps>

### Configuring Deps

1. **Lynx**

The core capabilities of [Lynx Engine](/guide/spec.html#engine) include basic capabilities such as parsing [Bundle](/guide/spec.html#lynx-bundle-or-bundle), style parsing, layout, and rendering views

Get the latest version of Lynx from Cocoapods. Then add Lynx to your Podfile:

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

2. **Lynx Service**

Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official. For example, `LynxImageService` is implemented using the [SDWebImage](https://github.com/SDWebImage/SDWebImage) image library by default. Apps that do not integrate SDWebImage components can rely on other image libraries to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;

Get the latest version of Lynx Service from Cocoapods. Then add Lynx Service to your Podfile:

<CodeFold height={360} toggle>

```ruby title="Podfile" {13-17,20-21}
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 dependencies:
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'
end
```

</CodeFold>

### Install Dependencies

Run `pod install` to install dependencies, then open your Xcode project. Additionally, make sure to disable the Sandbox Scripting capability.

:::note

In order to disable the **Sandbox scripting**, in Xcode click on your app, then on **build settings**. Filter for **script** and set the **User Script Sandboxing** to **NO**.

<img
  height="180px"
  width="640px"
  src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/integration_ios_warning.png"
/>
:::

</Steps>

## 2. Lynx Environment Initialization

<Steps>

### LynxEnv Initialization

LynxEnv provides a global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface call of the Lynx Engine.
For example, it can be initialized in `AppDelegate`

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">

```objective-c title=AppDelegate.m {6}
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxView.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [LynxEnv sharedInstance];
  return YES;
}
```

</Tab>
<Tab label="Swift">

```swift title=AppDelegate.swift {8}
import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    LynxEnv.sharedInstance()
    return true
  }
}

```
</Tab>
</Tabs>

</Steps>

## 3. Render LynxView

LynxView is the basic rendering unit provided by Lynx Engine. LynxView is an implementation inherited from iOS native [UIView](https://developer.apple.com/documentation/uikit/uiview). You can quickly construct a LynxView and add it to the [ViewController](https://developer.apple.com/documentation/uikit/uitab/viewcontroller/).

<Steps>


### Create Bundle Loader

Lynx Engine itself does not have the ability to load resources, so it is necessary to initialize LynxEnv, or when constructing [LynxView](/guide/spec.html#lynxview) to pass in the specific implementation of the `LynxTemplateProvider` protocol. Lynx will use the injected resource loader to obtain the Bundle content

You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.

1. First, please either generate the Bundle file from the [Quick Start](/guide/start/quick-start) phase or download the file below to your local machine, and then follow these steps to embed the file:

:::note
Bundle Example:
**https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle**
:::


:::note

Steps to embed files:
- In the target settings of the project, select the target;
- Select the **Build Phases** tab;
- In the **Copy Bundle Resources** section, click the add button (+) to add the file;

:::


2. Impl Bundle Loader

<Tabs groupId='integrating-lynx-with-existing-app-ios'>
<Tab label="Objective-C">

```objective-c title="DemoLynxProvider.h"
#import <Foundation/Foundation.h>
#import <Lynx/LynxTemplateProvider.h>

NS_ASSUME_NONNULL_BEGIN

@interface DemoLynxProvider : NSObject <LynxTemplateProvider>

@end

NS_ASSUME_NONNULL_END
```

</Tab>
<Tab label="Swift">

:::tip

Use [Bridging Header](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift) to import the required Lynx header files if you are using a Swift project, since Lynx is a project built with Objective-C.

:::

``` objective-c title="YourTarget-Bridging-Header.h"
#import <Lynx/LynxConfig.h>
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxTemplateProvider.h>
#import <Lynx/LynxView.h>
```

</Tab>
</Tabs>

<div style={{ marginBottom: 20 }} />

<Tabs groupId='integrating-lynx-with-existing-app-ios'>
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="DemoLynxProvider.m"
#import <Foundation/Foundation.h>

#import "DemoLynxProvider.h"

@implementation DemoLynxProvider

- (void)loadTemplateWithUrl:(NSString*)url onComplete:(LynxTemplateLoadBlock)callback {
    NSString *filePath = [[NSBundle mainBundle] pathForResource:url ofType:@"bundle"];
    if (filePath) {
      NSError *error;
      NSData *data = [NSData dataWithContentsOfFile:filePath options:0 error:&error];
      if (error) {
        NSLog(@"Error reading file: %@", error.localizedDescription);
        callback(nil, error);
      } else {
        callback(data, nil);
      }
    } else {
      NSError *urlError = [NSError errorWithDomain:@"com.lynx"
                                                  code:400
                                                userInfo:@{NSLocalizedDescriptionKey : @"Invalid URL."}];
      callback(nil, urlError);
    }
}

@end
```

</CodeFold>
</Tab>

<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="DemoLynxProvider.swift"
import Foundation

class DemoLynxProvider: NSObject, LynxTemplateProvider {
  func loadTemplate(withUrl url: String!, onComplete callback: LynxTemplateLoadBlock!) {
    if let filePath = Bundle.main.path(forResource: url, ofType: "bundle") {
      do {
        let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
        callback(data, nil)
      } catch {
        print("Error reading file: \(error.localizedDescription)")
        callback(nil, error)
      }
    } else {
      let urlError = NSError(domain: "com.lynx", code: 400, userInfo: [NSLocalizedDescriptionKey: "Invalid URL."])
      callback(nil, urlError)
    }
  }
}
```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Construct Basic LynxView

you may construct a basic LynxView as follows:

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {10-18}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
      builder.config = [[LynxConfig alloc] initWithProvider:[[DemoLynxProvider alloc] init]];
      builder.screenSize = self.view.frame.size;
      builder.fontScale = 1.0;
    }];
    lynxView.preferredLayoutWidth = self.view.frame.size.width;
    lynxView.preferredLayoutHeight = self.view.frame.size.height;
    lynxView.layoutWidthMode = LynxViewSizeModeExact;
    lynxView.layoutHeightMode = LynxViewSizeModeExact;
}
@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title=ViewController.swift {8-17}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    let lynxView = LynxView { builder in
      builder.config = LynxConfig(provider: DemoLynxProvider())
      builder.screenSize = self.view.frame.size
      builder.fontScale = 1.0
    }

    lynxView.preferredLayoutWidth = self.view.frame.size.width
    lynxView.preferredLayoutHeight = self.view.frame.size.height
    lynxView.layoutWidthMode = .exact
    lynxView.layoutHeightMode = .exact
  }
}
```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Add LynxView To The Window:

and then, adding the LynxView to the window.

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [self.view addSubview:lynxView];
}

@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    self.view.addSubview(lynxView)
  }
}

```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Render View

After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.loadTemplateFromURL` method to render the corresponding Bundle onto the LynxView.

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [lynxView loadTemplateFromURL:@"main.lynx" initData:nil];
}

@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    lynxView.loadTemplate(fromURL: "main.lynx", initData: nil)
  }
}

```

</CodeFold>
</Tab>
</Tabs>

Then you will see the following interface on the screen:

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-ios.png" width="200" />
</center>

</Steps>

Congratulations, you have now completed all the work of integrating Lynx Engine!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start) and [debugging](/guide/debugging/lynx-devtool) docs for in-depth insights on working with Lynx.

</PlatformTabs.Tab>

<PlatformTabs.Tab platform="android">
  ### Integrate Lynx with Existing Apps (Android)

import { Info, CodeFold } from '@lynx';
import { Steps } from '@theme';
import { Tab, Tabs } from 'rspress/theme';

<Info title="Lynx for Android">
  - This article assumes that you are familiar with the basic concepts of native Android application development.
  - You can refer to the project: [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/release/3.1) for all the code mentioned below.
</Info>

## 1. Dependency configuration

<Steps>

### Configuring Gradle

1. **Lynx**

The core capabilities of [Lynx Engine](/guide/spec.html#engine) include basic capabilities such as parsing [Bundle](/guide/spec.html#lynx-bundle-or-bundle), style parsing, layout, rendering views and the basic code of the javascript runtime that Lynx pages rely on

<Tabs groupId='integrating-lynx-with-existing-app-android-build'>
<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>

2. **Lynx Service**

Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official.For example, `LynxImageService` is implemented using the [Fresco](https://github.com/facebook/fresco) image library by default. Apps that do not integrate Fresco components can rely on other image libraries, such as [Glide](https://github.com/bumptech/glide) to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;

:::note
Since [Fresco](https://github.com/facebook/fresco) depends on [AndroidX](https://developer.android.com/jetpack/androidx), you also need to configure the following in gradle.properties:

```groovy
android.useAndroidX=true
```

:::

<Tabs groupId='integrating-lynx-with-existing-app-android-build'>
<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"

    implementation "com.squareup.okhttp3:okhttp:4.9.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"
}
```
</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>

<div style={{ marginBottom: 30 }} />

### Configure obfuscation rules ([Proguard](https://developer.android.com/build/shrink-code))

The obfuscation rules for` Lynx Engine` are as follows. It is recommended to refer to the latest source code configuration.

<CodeFold height={360} toggle>

```groovy title=proguard-rules.pro
# LYNX START
# use @Keep to annotate retained classes.
-dontwarn android.support.annotation.Keep
-keep @android.support.annotation.Keep class **
-keep @android.support.annotation.Keep class ** {
    @android.support.annotation.Keep <fields>;
    @android.support.annotation.Keep <methods>;
}
-dontwarn androidx.annotation.Keep
-keep @androidx.annotation.Keep class **
-keep @androidx.annotation.Keep class ** {
    @androidx.annotation.Keep <fields>;
    @androidx.annotation.Keep <methods>;
}

# native method call
-keepclasseswithmembers,includedescriptorclasses class * {
    native <methods>;
}
-keepclasseswithmembers class * {
    @com.lynx.tasm.base.CalledByNative <methods>;
}

# to customize a module, you need to keep the class name and the method annotated as LynxMethod.
-keepclasseswithmembers class * {
    @com.lynx.jsbridge.LynxMethod <methods>;
}

-keepclassmembers class *  {
    @com.lynx.tasm.behavior.LynxProp <methods>;
    @com.lynx.tasm.behavior.LynxPropGroup <methods>;
    @com.lynx.tasm.behavior.LynxUIMethod <methods>;
}

-keepclassmembers class com.lynx.tasm.behavior.ui.UIGroup {
    public boolean needCustomLayout();
}

# in case R8 compiler may remove mLoader in bytecode.
# as mLoader is not used in java and passed as a WeakRef in JNI.
-keepclassmembers class com.lynx.tasm.LynxTemplateRender {
    private com.lynx.tasm.core.LynxResourceLoader mLoader;
}

# the automatically generated setter classes use the class names of LynxBaseUI and ShadowNode and their subclasses.
-keep class com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class com.lynx.tasm.behavior.shadow.ShadowNode
-keep class com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class * extends com.lynx.tasm.behavior.shadow.ShadowNode
-keep class * extends com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.jsbridge.LynxContextModule
-keep class * implements com.lynx.tasm.behavior.utils.Settable
-keep class * implements com.lynx.tasm.behavior.utils.LynxUISetter
-keep class * implements com.lynx.tasm.behavior.utils.LynxUIMethodInvoker
-keep class com.lynx.tasm.rendernode.compat.**{
    *;
}
-keep class com.lynx.tasm.rendernode.compat.RenderNodeFactory{
    *;
}
# LYNX END
```

</CodeFold>

</Steps>

## 2. Environment Initialization

<Steps>

### Lynx Service Initialization

- Lynx Service provides host feature-related capabilities and it is recommended to complete the initialization of Lynx Service during the `Application#onCreate` lifecycle of the application.
- Lynx Service needs to be actively injected

:::tip

Please specify your custom Application class in the AndroidManifest.xml file, since Lynx needs to perform some global initialization operations when the application starts.

```xml title="/app/src/main/AndroidManifest.xml" {2}
<application
  android:name=".YourApplication">
</application>
```

:::

<Tabs groupId='integrating-lynx-with-existing-app-android'>
  <Tab label="Java">

<CodeFold height={360} toggle>
```java title=YourApplication.java {17,20-30}
import android.app.Application;

import com.facebook.drawee.backends.pipeline.Fresco;
import com.facebook.imagepipeline.core.ImagePipelineConfig;
import com.facebook.imagepipeline.memory.PoolConfig;
import com.facebook.imagepipeline.memory.PoolFactory;
import com.lynx.service.http.LynxHttpService;
import com.lynx.service.image.LynxImageService;
import com.lynx.service.log.LynxLogService;
import com.lynx.tasm.service.LynxServiceCenter;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
    }

    private void initLynxService() {
        // init Fresco which is needed by LynxImageService
        final PoolFactory factory = new PoolFactory(PoolConfig.newBuilder().build());
        ImagePipelineConfig.Builder builder =
                ImagePipelineConfig.newBuilder(getApplicationContext()).setPoolFactory(factory);
        Fresco.initialize(getApplicationContext(), builder.build());

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance());
        LynxServiceCenter.inst().registerService(LynxLogService.INSTANCE);
        LynxServiceCenter.inst().registerService(LynxHttpService.INSTANCE);
    }
}
```
</CodeFold>

  </Tab>
  <Tab label="Kotlin">

<CodeFold height={360} toggle>
```kotlin title=YourApplication.kt {15,18-27}
import android.app.Application
import com.facebook.drawee.backends.pipeline.Fresco
import com.facebook.imagepipeline.core.ImagePipelineConfig
import com.facebook.imagepipeline.memory.PoolConfig
import com.facebook.imagepipeline.memory.PoolFactory
import com.lynx.service.http.LynxHttpService
import com.lynx.service.image.LynxImageService
import com.lynx.service.log.LynxLogService
import com.lynx.tasm.service.LynxServiceCenter

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
    }

    private fun initLynxService() {
        // init Fresco which is needed by LynxImageService
        val factory = PoolFactory(PoolConfig.newBuilder().build())
        val builder = ImagePipelineConfig.newBuilder(applicationContext).setPoolFactory(factory)
        Fresco.initialize(applicationContext, builder.build())

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance())
        LynxServiceCenter.inst().registerService(LynxLogService)
        LynxServiceCenter.inst().registerService(LynxHttpService)
    }
}
```
</CodeFold>

  </Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### LynxEnv Initialization

LynxEnv provides the global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface calls to the Lynx Engine. It is recommended to complete the initialization of LynxEnv during the Application#onCreate lifecycle of the application.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
  <Tab label="Java">

<CodeFold height={360} toggle>
```java title=YourApplication.java {9,12-19}
import com.lynx.tasm.LynxEnv;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
        initLynxEnv();
    }

    private void initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        );
    }
}
```
</CodeFold>

</Tab>

  <Tab label="Kotlin">

<CodeFold height={360} toggle>
```kotlin title=YourApplication.kt {8,11-18}
import com.lynx.tasm.LynxEnv

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
        initLynxEnv()
    }

    private fun initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        )
    }
}
```
</CodeFold>

</Tab>
</Tabs>


:::tip

The parameters for the LynxEnv initialization method are described as follows:
- **appContext**: The context object for the application lifecycle, i.e., ApplicationContext.
- **libraryLoader**: The loader for native so files, the default value can be null, which will use the system default loader.
- **templateProvider**: The global AppBundle loader, the default value can be null;
- **behaviorBundle**: The list of custom components, the default value can be null. If there are customization requirements, please refer to [custom-native-component](/guide/custom-native-component)

:::

</Steps>

## 3. Render LynxView

<Steps>

### Create Bundle Loader
Lynx Engine itself does not have the ability to integrate downloading resources, so the existing app needs to provide the specific implementation of `AbsTemplateProvider`, and inject it when initializing LynxEnv or constructing [LynxView](/guide/spec.html#lynxview). Lynx will use the injected resource loader to obtain the Bundle content

You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.

1. First, please place the Bundle file generated in the [Quick Start](/guide/start/quick-start) stage in the src/main/assets directory, or you can download the file below to your local machine and place it in the same directory:

:::note
Bundle Example:
**https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle**
:::

```
app
└── src
    └── main
        ├── java
        ├── res
        └── assets
            └── main.lynx.bundle
```

2. Impl Bundle Loader

<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">

<CodeFold height={360} toggle>

```java title="DemoTemplateProvider.java" {}
import android.content.Context;
import com.lynx.tasm.provider.AbsTemplateProvider;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;

public class DemoTemplateProvider extends AbsTemplateProvider {
    private Context mContext;

    DemoTemplateProvider(Context context) {
        this.mContext = context.getApplicationContext();
    }

    @Override
    public void loadTemplate(String uri, Callback callback) {
        new Thread(new Runnable() {
            @Override
            public void run() {
                try (InputStream inputStream = mContext.getAssets().open(uri);
                     ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream()) {
                    byte[] buffer = new byte[1024];
                    int length;
                    while ((length = inputStream.read(buffer)) != -1) {
                        byteArrayOutputStream.write(buffer, 0, length);
                    }
                    callback.onSuccess(byteArrayOutputStream.toByteArray());
                } catch (IOException e) {
                    callback.onFailed(e.getMessage());
                }
            }
        }).start();
    }
}
```

</CodeFold>

</Tab>
<Tab label="Kotlin">

<CodeFold height={360} toggle>

```kotlin title="DemoTemplateProvider.kt" {}
import android.content.Context
import com.lynx.tasm.provider.AbsTemplateProvider
import java.io.ByteArrayOutputStream
import java.io.IOException

class DemoTemplateProvider(context: Context) : AbsTemplateProvider() {

    private var mContext: Context = context.applicationContext

    override fun loadTemplate(uri: String, callback: Callback) {
        Thread {
            try {
                mContext.assets.open(uri).use { inputStream ->
                    ByteArrayOutputStream().use { byteArrayOutputStream ->
                        val buffer = ByteArray(1024)
                        var length: Int
                        while ((inputStream.read(buffer).also { length = it }) != -1) {
                            byteArrayOutputStream.write(buffer, 0, length)
                        }
                        callback.onSuccess(byteArrayOutputStream.toByteArray())
                    }
                }
            } catch (e: IOException) {
                callback.onFailed(e.message)
            }
        }.start()
    }
}
```

</CodeFold>

</Tab>
</Tabs>

### Construct LynxView

`LynxView` is the basic rendering view provided by `Lynx Engine`. `LynxView` inherits from the native Android [View](https://developer.android.com/reference/android/view/View). You can quickly construct a LynxView and add it arbitrarily to the native Android view tree.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">
```java title=MainActivity.java {12-13,16-20}
import android.app.Activity;
import android.os.Bundle;

import com.lynx.tasm.LynxView;
import com.lynx.tasm.LynxViewBuilder;

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);
    }

    private LynxView buildLynxView() {
        LynxViewBuilder viewBuilder = new LynxViewBuilder();
        viewBuilder.setTemplateProvider(new DemoTemplateProvider(this));
        return viewBuilder.build(this);
    }
}
```
</Tab>

<Tab label="Kotlin">
```kotlin title=MainActivity.kt {11-12,15-19}
import android.app.Activity
import android.os.Bundle
import com.lynx.tasm.LynxView
import com.lynx.tasm.LynxViewBuilder


class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)
    }

    private fun buildLynxView(): LynxView {
        val viewBuilder = LynxViewBuilder()
        viewBuilder.setTemplateProvider(DemoTemplateProvider(this))
        return viewBuilder.build(this)
    }
}
```

</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### 3.1 Render view

After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.renderTemplateUrl` method to render the corresponding Bundle onto the LynxView view.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">

```java title=MainActivity.java {9-10}
public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);

        String url = "main.lynx.bundle";
        lynxView.renderTemplateUrl(url, "");
    }
}
```

</Tab>
<Tab label="Kotlin">

```kotlin title=MainActivity.kt {8-9}
class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)

        val uri = "main.lynx.bundle";
        lynxView.renderTemplateUrl(uri, "")
    }
}
```

</Tab>
</Tabs>

Then you will see the following interface on the screen:

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-android.png" width="200" />
</center>

</Steps>

Congratulations, you have now completed all the work of rendering the LynxView!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start) and [debugging](/guide/debugging/lynx-devtool) docs for in-depth insights on working with Lynx.

</PlatformTabs.Tab>

<PlatformTabs.Tab platform="web">
  ### Integrate Lynx with Existing Apps (Web)

import { PackageManagerTabs, Steps } from '@theme';
import { Info } from '@lynx';

<Info title="Lynx for Web">
  Lynx for Web implements the Lynx engine in web browsers. With Lynx for Web,
  you can easily integrate Lynx apps into any existing web project, regardless
  of whether the project uses React, Vue, Svelte, or plain HTML.
</Info>

## 1. Build web artifact

We need you to have read and created a Lynx project according to [Quick Start](/guide/start/quick-start).

<Steps>

### Add web configuration

1. Enter the previously created Lynx project:

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

2. Add web configuration (`environments.web`) to `lynx.config.ts`:

```ts
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [pluginReactLynx()],
  environments: {
    web: {
      output: {
        assetPrefix: '/',
      },
    },
    lynx: {},
  },
});
```

### Build

Run:

<PackageManagerTabs command="run build" />

You will see an additional `dist/main.web.bundle` file in this project, which is the final web build artifact.

</Steps>

## 2. Integrate with a new web project

Now that you have a Lynx for Web build artifact, we need to create a web project to use it. Here we use Rsbuild.

<Steps>

### Create a web project

Create a new project at the same level as the Lynx project above and run:

<PackageManagerTabs command="create rsbuild@latest" />

Follow the prompts to create a React project.

### Configure the project

1. Navigate to the created project:

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

2. Install dependencies

<PackageManagerTabs command="install @lynx-js/web-core @lynx-js/web-elements" />

3. Import these dependencies in `src/app.tsx`

```tsx
import './App.css';
import '@lynx-js/web-core/index.css';
import '@lynx-js/web-elements/index.css';
import '@lynx-js/web-core';
import '@lynx-js/web-elements/all';

const App = () => {
  return (
    <lynx-view
      style={{ height: '100vh', width: '100vw' }}
      url="/main.web.bundle"
    ></lynx-view>
  );
};

export default App;
```

4. Update `rsbuild.config.ts`

:::warning
`server.publicDir` needs to be replaced with your actual Lynx project path.
:::

```ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default defineConfig({
  plugins: [pluginReact()],
  server: {
    publicDir: [
      {
        name: path.join(
          __dirname,
          '../',
          // Please replace this with your actual Lynx project name
          'lynx-project',
          'dist',
        ),
      },
    ],
  },
});
```

### Start the project

Run:

<PackageManagerTabs command="run dev" />

Visit `http://localhost:3000` to see your Lynx application.

</Steps>

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

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

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.

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

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.

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.

Scan the QR code to download the pre-built app from the [GitHub Release](https://github.com/lynx-family/lynx/releases/latest).

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

### Start developing

1. Navigate to the created project:

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

2. Install the NPM dependencies with package manager:

3) To start the development server, run:

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.

### 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/debugging/lynx-devtool.md), learn how to debug your Lynx app.

## Next steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

### Describing UI

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

### Integration

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



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

## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/Pictures.tar.gz) to use in your projects.

## Adding Styles

Since the focus of this tutorial is not on how to style your UI, you may just save some time and directly copy the below `index.css` file:

```css title="index.scss"
.gallery-wrapper {
  height: 100vh;
  background-color: black;
}

.single-card {
  display: flex;
  align-items: center;
  justify-content: center;
}

.scrollbar {
  position: absolute;
  right: 7px;
  z-index: 1000;
  width: 4px;
  background: linear-gradient(to bottom, #ff6448, #ccddff, #3deae7);
  border-radius: 5px;
  overflow: hidden;
  box-shadow:
    0px 0px 4px 1px rgba(12, 205, 223, 0.4),
    0px 0px 16px 5px rgba(12, 205, 223, 0.5);
}

.scrollbar-effect {
  width: 100%;
  height: 80%;
}

.glow {
  background-color: #333;
  border-radius: 4px;
  background: linear-gradient(
    45deg,
    rgba(255, 255, 255, 0) 20%,
    rgba(255, 255, 255, 0.8) 50%,
    rgba(255, 255, 255, 0) 80%
  );
  animation: flow 3s linear infinite;
}

@keyframes flow {
  0% {
    transform: translateY(-100%);
  }
  100% {
    transform: translateY(100%);
  }
}

.list {
  width: 100vw;
  padding-bottom: 20px;
  padding-left: 20px;
  padding-right: 20px;
  height: calc(100% - 48px);
  list-main-axis-gap: 10px;
  list-cross-axis-gap: 10px;
}

.picture-wrapper {
  border-radius: 10px;
  overflow: hidden;
  width: 100%;
}

.like-icon {
  position: absolute;
  display: grid;
  justify-items: center;
  align-items: center;
  top: 0px;
  right: 0px;
  width: 48px;
  height: 48px;
}

.heart-love {
  width: 16px;
  height: 16px;
}

.circle {
  position: absolute;
  top: calc(50% - 8px);
  left: calc(50% - 8px);
  height: 16px;
  width: 16px;
  border: 2px solid red;
  border-radius: 50%;
  transform: scale(0);
  opacity: 1;
  animation: ripple 1s 1 ease-out;
}

.circleAfter {
  animation-delay: 0.5s;
}

@keyframes ripple {
  0% {
    transform: scale(1);
    opacity: 1;
  }
  100% {
    transform: scale(2);
    opacity: 0;
  }
}
```

and import it as a global styles:

```js
import '../index.css';
```

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.

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

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

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

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:

Similar to the `bindtap` event used to add the like functionality, we add the bindscroll event to `<list>`, which will be triggered when the `<list>` element scrolls.

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

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:

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:

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.

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

1. Card Details
   * The card can perform flip animation
   * Here we'll learn how to use CSS animations to create smooth flip effects

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

3. The top amount display and bottom buttons, these components are relatively simple, we'll implement them using the [view](/api/elements/built-in/view.md) element.

Let's focus on three technical points: building an interactive scrolling list, implementing 3D flip animation effects, and passing data between components.

### Building an Interactive Card List

First, let's create a bank card list. This list needs to display basic information for each card, including:

* Bank type (like Bac, Boc, etc.)
* Card number (showing first and last four digits)
* Cardholder name
* Whether it's a primary card

Let's organize this information into a data structure:

```tsx title="BankCardScrollView.tsx"
export interface BankCard {
  type: string; // Bank type (like Bac, Boc, etc.)
  number: string; // Card number
  name: string; // Cardholder name
}
```

Then, prepare some card data for display:

```tsx title="BankCardScrollView.tsx"
const cards = [
  { type: "bac", number: "4558 **** **** 6767", name: "Alex Quentin" },
  { type: "boc", number: "6222 **** **** 8058", name: "Alex Quentin" },
  ...
];
```

Next, let's use the `<scroll-view>` element to create a vertically scrollable list to display all card information:

```tsx title="BankCardScrollView.tsx" {6}
export default function BankCardScrollView() {
  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

To let users know which card they've selected, we need to add an icon to indicate selection:

```scss title="BankCardScrollView.tsx"
<image className="check-icon" src={checkIcon} />
```

Then, we need to define a `selectedCard` state to track the currently selected card:

```tsx title="BankCardScrollView.tsx"
const [selectedCard, setSelectedCard] = useState(cards[0]);
```

After that, we need to add a `handleCardSelect` function in the `<BankCardScrollView>` component to handle card selection events:

```tsx title="BankCardScrollView.tsx"
const handleCardSelect = (card: BankCard) => {
  setSelectedCard(card);
};
```

When a user clicks a card, it will trigger the `handleCardSelect` function, which will update the `selectedCard` state:

```tsx title="BankCardScrollView.tsx" {3}
<view
  className={`card ${selectedCard === card ? 'selected' : ''}`}
  bindtap={() => handleCardSelect(card)}
>
  ...
</view>
```

Let's combine the above logic. When a user selects a card, it will show a small check mark on the right to indicate the current selection:

```tsx title="BankCardScrollView.tsx {5,17}"
export default function BankCardScrollView() {
  const [selectedCard, setSelectedCard] = useState(cards[0]);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
  };

  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
              {selectedCard === card && (
                <image className="check-icon" src={checkIcon} />
              )}
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

Now, we've completed building this interactive card list. Let's see how it works!

### 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](/en/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](/en/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](/en/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.

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

We'll add the top amount display, and we're done!

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

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

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](/en/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/en/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>;
}
```

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](/en/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.

## 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](/en/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

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`](/en/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.

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

### 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`](/en/api/react/Function.runOnMainThread.md)
* From main thread to background: Use [`runOnBackground`](/en/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);
    }
  }
}
```

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:

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.

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.

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

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.

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

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

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

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

Lynx elements are designed to be platform-agnostic. They are rendered natively by the Lynx Engine into the UI primitives for each platforms, such as iOS and Android views, or HTML elements (including [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)) on the Web.

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

| Element                                               | Android                  | iOS                               | Web analogy                    | Description                                                                                                               |
| :---------------------------------------------------- | :----------------------- | :-------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| [`<view>`](/api/elements/built-in/view.md)               | `ViewGroup`              | `UIView`                          | 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`                      | `<p>`                          | Used for displaying text content. Specific text styles can be aligned.                                                    |
| [`<image>`](/api/elements/built-in/image.md)             | `ImageView`              | `UIImageView`                     | `<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`                    | `<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`                | 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 | Non-resizable `<body>`         | Root node of a page, usually doesn't need to be added manually.                                                           |

## Extending with Custom Elements

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

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

## Components: Composition of Elements

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

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

***

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



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



# Styling with CSS

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

:::tip

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

:::

## Selectors and inline styles

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

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

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

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.

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

## CSS Variables and Opt-in Inheritance

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

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

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



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



# Understanding Layout

Lynx provides:

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

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

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

## Sizing the Elements

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

By default, the size properties of Lynx, such as `width`, `height`, and `max-width`, describe the size of the border box. This is inconsistent with the default behavior of the Web.

Lynx does not exhibit the behavior of [margin collapsing](https://developer.mozilla.org/en/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) as in the Web.

## Layout the Elements

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

### Linear Layout

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

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

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

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

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

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

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

The CSS properties of Lynx are not inheritable by default. If you want the
[`direction`](/api/css/properties/direction.md) to be inheritable, please refer
to [CSS
Inheritance](/guide/styling/custom-theming.md#how-to-enable-css-inheritance)

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



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



# Linear Layout

If you want to arrange children sequentially without dealing with the complexities of [flexible box](/en/guide/ui/layout/flexible-box-layout.md) and [grid](/en/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](/en/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;
```

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

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

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.

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

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

## Reference

Currently, the linear layout supports the following layout properties:

* **Specific CSS Properties**

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

* **Alignment Properties**

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

* **Other Properties**

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



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



# Flexible Box Layout

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

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

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

## Typical Features

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

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

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

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.

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

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

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

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

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

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

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

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

## Reference

Currently, Lynx supports the following common grid layout properties:

* **CSS Properties**

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

* **Alignment Properties**

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



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



# Relative Layout

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](/en/guide/ui/layout/grid-layout.md), [flexible box](/en/guide/ui/layout/flexible-box-layout.md), and [linear](/en/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.

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

In this example, the container's width is fixed, while its height adjusts to its content. To incorporate gaps between elements, use `margin`.

* **Best Practices**

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

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

## Reference

* **Relative Id**

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

* **Edge Alignment Properties**

  **Physical Properties**

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

  **Logical Properties**

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

* **Relative Position Properties**

  **Physical Properties**

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

  **Logical Properties**

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

* **Center Property**

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

* **Layout Optimization Property**

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



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



# Managing Scrolling

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

non-scrollable element

scrollable element

Content overflow has occurred.

crop the overflowing content through <code>overflow: hidden</code>

<code>scroll-orientation: vertical</code> scrollable element&#x20;

<code>scroll-orientation: horizontal</code> scrollable element

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

## scrollable element

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

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

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

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

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

### Additional Features

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

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

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



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



# Event Handling

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

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

## What is an event

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

**Example 1:**

## Listen for user clicks

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

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

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

## Handling user clicks

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

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

When the event processing function is a [main thread script](/en/react/main-thread-script.md), you need to add a [`'main thread'`](/en/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`.

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

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

**Example 2**

### 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`](/en/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md) Modify the background color of the node.

**Example 3:**

## 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](/en/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](/en/api/lynx-api/event/touch-event.md), the event response chain only contains the node where the action is actually triggered.

**Example 1:**

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

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

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

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.

## Cross-component event listening

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

It should be noted that for non-[touch events](/en/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`](/en/api/elements/built-in/view.md#id) are listened (type is `string`, multiple [`id`](/en/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`](/en/api/lynx-api/lynx/lynx-before-publish-event.md)) provided by Lynx to implement the corresponding function.

**Example 6:**

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`](/en/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:**

For the client, the example is as follows:

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

```java
// You can call the sendGlobalEvent function of LynxContext
// The first parameter is the event name monitored by the front end, and the second parameter is the data received by the front end
LynxContext.sendGlobalEvent("eventName", args);
// Or call the sendGlobalEvent function of LynxView
LynxView.sendGlobalEvent("eventName", args);
```

### 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`](/en/api/lynx-api/event/global-event.md#onwindowresize) event sent by Lynx, which is triggered when the Lynx page size changes.

**Example 8:**



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

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:

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:

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

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

## Using `getElementById` API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



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



# Visibility detection

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

## Detect whether a node is exposed

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

[Exposure ability](/en/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`](/en/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`](/en/api/elements/built-in/view.md#exposure-id) visible on the screen in real time.

**Example 2:**

Since the exposure capability focuses on whether the node is visible, the node visibility requirement here is more stringent. In addition, since [exposure capability](/en/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`](/en/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](/en/guide/interaction/visibility-detection/intersection-observer.md).

The [intersection observer](/en/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`](/en/api/elements/built-in/view.md#id) and the intersection position when they intersect.

**Example 1:**

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](/en/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](/en/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](/en/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.

## 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`](/en/api/lynx-api/event/global-event.md#exposure) and anti-exposure event [`disexposure`](/en/api/lynx-api/event/global-event.md#disexposure) of the node with the [`exposure-id`](/en/api/elements/built-in/view.md#exposure-id) attribute set through [`GlobalEventEmitter`](/en/guide/interaction/event-handling/event-propagation.md#globaleventemitter).

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

**Example 1:**

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`](/en/api/elements/built-in/view.md#binduiappear) and [`uidisappear`](/en/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`](/en/api/elements/built-in/view.md#id) when it is exposed.

**Example 2:**

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`](/en/api/lynx-api/lynx/lynx-stop-exposure.md): used 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`](/en/api/lynx-api/lynx/lynx-resume-exposure.md): used 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`](/en/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-*`](/en/api/elements/built-in/view.md#exposure-screen-margin-), [`exposure-ui-margin-*`](/en/api/elements/built-in/view.md#exposure-ui-margin-), [`exposure-area`](/en/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`](/en/api/lynx-api/lynx/lynx-create-intersection-observer.md) to create an [`IntersectionObserver`](/en/api/lynx-api/intersection-observer.md) object and specify the threshold list of intersection status changes.
2. Call the [`relativeTo`](/en/api/lynx-api/intersection-observer.md) method of the [`IntersectionObserver`](/en/api/lynx-api/intersection-observer/intersection-observer-relative-to.md) object to specify the reference node.
3. Call the [`observe`](/en/api/lynx-api/intersection-observer.md) method of the [`IntersectionObserver`](/en/api/lynx-api/intersection-observer.md) object to specify the target node and callback.
4. Call the [`disconnect`](/en/api/lynx-api/intersection-observer.md) method of the [`IntersectionObserver`](/en/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`](/en/api/elements/built-in/view.md#id) and the intersection position when they intersect.

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



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

# Networking

Many mobile apps need to load resources from remote URLs. You might want to make a POST request to a REST API, or you might need to 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 the [Fetch API](/api/lynx-api/global/fetch.md) with the same usage as the Web. You can refer to the MDN guides on [Using Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) for more information.

This is an example app that fetches and displays user posts provided by the [JSONPlaceholder API](https://jsonplaceholder.typicode.com/). It initializes with a loading state and, upon mounting, triggers a Fetch API request to retrieve posts. The fetched data is then displayed in a scrollable list where each post is shown with its ID and title. If the request is still in progress, a "Loading..." message appears.



### Making requests

In order 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 JSON-based `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. `fetch` method will return a `Promise` that makes it straightforward to write code that works in an asynchronous manner. You can use the `async/await` syntax to wait the `promise` to end:

```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 may be thrown by `fetch`, otherwise they will be dropped silently.

## Using Other Networking Libraries

Since The Fetch API is built into Lynx. This means that you can use third party libraries that depend 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 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 Web ecosystem.

For frontend 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 ReactLynx guide.



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



# Instant First-Frame Rendering (IFR)

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

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

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

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

:::

## Basic Example

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

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

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

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



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

# Visual Appearance



## Background and Borders

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

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

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

Text with a gradient <code>color</code>

Filling background with <code>radial-gradient</code>

&#x20;Create a 'fading edge' effect by adding <code>linear-gradient</code> to <code>mask-image</code>property

## Clipping and Masking

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

Using clip-path to clip out a super-elliptical area

Using mask-image to create a circle area with fading edge



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



# Motion

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

## Add transitions for layout and style changes.

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

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

Transitions are automatically triggered, non-repetitive, and easy to use. They can be defined using the shorthand [`transition`](/en/api/css/properties/transition.md) to set animation properties and duration, or you can specify them individually with [`transition-property`](/en/api/css/properties/transition-property.md) and [`transition-duration`](/en/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:

## 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`](/en/api/css/at-rule/keyframes.md) rule, which specifies the style changes at various stages of the animation. The [`animation`](/en/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`](/en/api/css/at-rule/keyframes.md) and specify them using the shorthand [`animation`](/en/api/css/properties/animation.md) property, or define them with individual properties such as [`animation-name`](/en/api/css/properties/animation-name.md), [`animation-duration`](/en/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.

### To achieve a spring effect

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

## Create flexible keyframe animations in JS.

Additionally, our [animate api](/en/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.



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

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

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

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

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

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.

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.

In addition to images, you can also nest `<view>` within the `<text>` component to create more complex pages.

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

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



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

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

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

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

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



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

:::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" {3,12}
import { useEffect } from '@lynx-js/react';

import { i18n } from './i18n.js';

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.

```js
// Static-imported locales that can be shown at first screen
import enTranslation from './locales/en.json';
import zhTranslation from './locales/zh.json';
import itTranslation from './locales/it.json';
import jpTranslation from './locales/jp.json';
import deTranslation from './locales/de.json';
import esTranslation from './locales/es.json';
import frTranslation from './locales/fr.json';
import idTranslation from './locales/id.json';
import ptTranslation from './locales/pt.json';
```

```js
const localesContext = import.meta.webpackContext('./locales', {
  recursive: false,
  regExp: /\.json$/,
});
const enTranslation = localesContext('en.json');
```

These resources can be added to `i18next.init()` to make translation work at the first screen.

```typescript title="src/i18n.ts"
import i18next from 'i18next';
import type { i18n } from 'i18next';

// Localizations imported statically, available at the initial screen
const localesContext = import.meta.webpackContext('./locales', {
  recursive: false,
  regExp: /\.json$/,
});

const localI18nInstance: i18n = i18next.createInstance();

localI18nInstance.init({
  lng: 'en',
  // The default JSON format needs Intl.PluralRules API, which is currently unavailable in Lynx.
  compatibilityJSON: 'v3',
  // Add all statically imported localizations to i18next resources.
  resources: Object.fromEntries(
    localesContext.keys().map((key) => [
      key.match(/\/([^/]+)\.json$/)?.[1] || key,
      {
        translation: localesContext(key) as Record<string, string>,
      },
    ]),
  ),
});

export { localI18nInstance as i18n };
```

:::tip
You may need [Rspeedy Type Declaration](/rspeedy/typescript.md#rspeedy-type-declaration) for `import.meta.webpackContext`.
:::

### Load resources asynchronously and lazily

Instead of bundling all the locales, we can use dynamic imports (`import()`) to load the locales lazily and asynchronously.

You need to install the [`i18next-resources-to-backend`](https://github.com/i18next/i18next-resources-to-backend) package:

Then add the following code to `src/i18n.ts`:

```typescript title="src/i18n.ts" {3,14-23,38}
import i18next from 'i18next';
import type { i18n } from 'i18next';
import resourcesToBackend from 'i18next-resources-to-backend';

// Localizations imported statically, available at the initial screen
const localesContext = import.meta.webpackContext('./locales', {
  recursive: false,
  regExp: /(en|zh)\.json$/,
});

const localI18nInstance: i18n = i18next.createInstance();

// We can only loading resources on a background thread
if (__JS__) {
  localI18nInstance.use(
    // See: https://www.i18next.com/how-to/add-or-load-translations#lazy-load-in-memory-translations
    resourcesToBackend(
      (language: string) =>
        // Dynamic-imported locales can be used with `i18n.loadLanguages`
        import(`./locales/${language}.json`),
    ),
  );
}

localI18nInstance.init({
  lng: 'en',
  // The default JSON format needs Intl.PluralRules API, which is currently unavailable in Lynx.
  compatibilityJSON: 'v3',
  // Add all statically imported localizations to i18next resources.
  resources: Object.fromEntries(
    localesContext.keys().map((key) => [
      key.match(/\/([^/]+)\.json$/)?.[1] || key,
      {
        translation: localesContext(key) as Record<string, string>,
      },
    ]),
  ),
  partialBundledLanguages: true,
});

export { localI18nInstance as i18n };
```

1. An `i18next` backend `i18next-resources-to-backend` has been added to the background thread with `localI18nInstance.use`.

2. The languages can be loaded asynchronously (with some of them being loaded synchronously).

You will see two async JS chunks are created in the output:

```js title=src_locales_it-IT_json.js
'use strict';
exports.ids = ['src_locales_it-IT_json'];
exports.modules = {
  './src/locales/it-IT.json': function (module) {
    module.exports = JSON.parse('{"world": "Mondo"}');
  },
};
```

```js title=src_locales_ja-JP_json.js
'use strict';
exports.ids = ['src_locales_ja-JP_json'];
exports.modules = {
  './src/locales/ja-JP.json': function (module) {
    module.exports = JSON.parse('{"world": "世界"}');
  },
};
```

:::tip 💡 Why is there no async chunk generated by src/locales/en.json

This is because this module is already included in the main chunk. Webpack/Rspack will remove it automatically.
See: [`optimization.removeAvailableModules`](https://webpack.js.org/configuration/optimization/#optimizationremoveavailablemodules) and [`optimization.removeEmptyChunks`](https://webpack.js.org/configuration/optimization/#optimizationremoveemptychunks) for details.

You may also see that these two chunks are not loaded. This is why it is called lazily. The request to the resources is only sent when needed.
:::

You may also see that these two chunks are not loaded. This is why it is called lazily. The request to the resources is only sent when needed.

### Change between languages

The `i18next.changeLanguage` API can be used for changing between languages.

```jsx title="src/App.tsx"
import { useEffect, useState } from '@lynx-js/react';

import { i18n } from './i18n.js';

export function App() {
  const [locale, setLocale] = useState('en');

  useEffect(() => {
    console.log('Hello, ReactLynx3 x i18next!');
  }, []);

  const getNextLocale = (locale: string) => {
    // mock locales
    const locales = ["en", "zh-CN"];
    const index = locales.indexOf(locale);
    return locales[(index + 1) % locales.length];
  };
  return (
    <view>
      <text style={{ color: 'red' }}>Current locale: {locale}</text>
      <text
        bindtap={async () => {
          const nextLocale = getNextLocale(locale);
          await i18n.changeLanguage(nextLocale);
          setLocale(nextLocale);
        }}
      >
        Tap to change locale
      </text>
      <text>Hello, {i18n.t('world')}</text>
    </view>
  );
}
```



---
url: /guide/debugging/lynx-devtool.md
---

# Lynx DevTool

Lynx DevTool is a collection of performance and debugging tools for Lynx apps.

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

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

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

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

:::tip Tip
After switching devices, please ensure that the Lynx app on the device is running in the foreground.
:::

## Choose Page and Debugging Options

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.

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/debugging/lynx-devtool/elements-panel.md#view-dom-nodes)
* [Edit the Element](/guide/debugging/lynx-devtool/elements-panel.md#edit-the-dom)
* [View and Change CSS](/guide/debugging/lynx-devtool/elements-panel.md#view-and-change-css)
* [Find Invalid, Overridden, and Other CSS](/guide/debugging/lynx-devtool/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/debugging/lynx-devtool/console-panel.md#view-logged-messages)
* [Run JavaScript](/guide/debugging/lynx-devtool/console-panel.md#run-javascript)
* [Clear the Console](/guide/debugging/lynx-devtool/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/debugging/lynx-devtool/sources-panel.md#file-navigation)
* [Pause Code with Breakpoints](/guide/debugging/lynx-devtool/sources-panel.md#pause-code-with-breakpoints)
* [Debug JavaScript](/guide/debugging/lynx-devtool/sources-panel.md#debug-javascript)
* [Debug Original Code with Source Maps](/guide/debugging/lynx-devtool/sources-panel.md#debug-original-code-with-source-maps)
* [Debug the Main Thread](/guide/debugging/lynx-devtool/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/debugging/lynx-devtool/layers-panel.md#view-page-layers)
* [Inspect page Layers](/guide/debugging/lynx-devtool/layers-panel.md#inspect-page-layers)

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

## 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/debugging/lynx-devtool/elements-panel.md
---

{`
  .full_image {
    width: 800px;
    margin: 20px;
  }
  `}

# Elements Panel

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

## Overview

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

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

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

### Open the Elements Panel

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

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

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



---
url: /guide/debugging/lynx-devtool/console-panel.md
---

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

# Console Panel

## Overview

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

<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">
  Click **Console Settings**&#x20;

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

  &#x20;in the top-right corner of the **Console** panel.
</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](/en/guide/debugging/lynx-devtool/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](/en/guide/debugging/lynx-devtool/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">
  For JavaScript errors and warnings, click **Expand**&#x20;

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

  &#x20;to view the stack trace.
</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](/en/guide/debugging/lynx-devtool/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">
    Click **Clear Console**

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

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



---
url: /guide/debugging/lynx-devtool/sources-panel.md
---



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

# Sources Panel

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

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

To switch to the V8 engine, open the [DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch), toggle the "**V8 Engine**" switch to "**On**" and restart the application. You can check the current engine type in the lower-left corner of the [Preview Window](/guide/debugging/lynx-devtool/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.

## File Navigation

### Open File

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

Click **More Options**&#x20;

and select **Open file**. A dialog will display.

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

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

Click **Show navigator**&#x20;

button to collapse/expand the **File Navigation Pane**.

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

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

### Search Code

To search a code segment:

1. Click **Customize And Control DevTools**
   <img
     src={
       'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/more-options.png'
     }
     alt="More options"
   />
   &#x20;\> **Search** to open the **Search** panel.
   <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.

You can also:

* Click **Match Case**&#x20;
  <img
    src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/match-case.png'
    }
    alt="Step out"
  />
  to make the query case-sensitive.
* Click **Use Regular Expression**&#x20;
  <img
    src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/use-regular.png'
    }
    alt="Step out"
  />
  to search using a RegEx.
* Click **Refresh**&#x20;
  <img
    src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/refresh.png'
    }
    alt="Step out"
  />
  to search again.
* Click **Clear**&#x20;
  <img
    src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/clear.png'
    }
    alt="Step out"
  />
  to clear the input contents.

## Pause Code with Breakpoints

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

Currently supported breakpoint types are as follows:

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

### Line-of-Code Breakpoints

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

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

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

#### Conditional Line-of-Code Breakpoints

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

#### Log Line-of-Code breakpoints

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

#### Manage Line-of-Code Breakpoints

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

* Right-click the breakpoint icon and select **Edit breakpoint** to edit it. You can also change its type from the drop-down list in the inline editor.

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

* Right-click the breakpoint icon to see the options menu:
  * Remove breakpoint.
  * Edit breakpoint.
  * Disable/Enable breakpoint.

* Right-click the breakpoint entry in the **Breakpoints** pane to see the options menu:
  * Remove breakpoint.
  * Reveal location.
  * Deactivate/Activate breakpoints.

    You can also use **Deactivate breakpoints**&#x20;

    button to deactivate breakpoints.

    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.

#### Skip Breakpoints with 'Never Pause Here' Background V8 Only

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

### First-Line Breakpoints Background Only

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

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.

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](/en/guide/debugging/lynx-devtool/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.

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

#### Step Over

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

#### Step Into

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

#### Step Out

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

#### Run All Code Up to a Certain Line Background V8 Only

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

#### Resume

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

##### Terminate Execution Background V8 Only

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

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.

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

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

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

### Ignore Scripts Background V8 Only

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

#### Ignore a Script from the Editor Pane

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

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

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

#### Show ignore-listed frames

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

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

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

#### Edit Scripts Background V8 Only

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

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

#### Search and Replace Text in Scripts

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

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

## Debug Original Code with Source Maps Background Only

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

### Check If Source Maps Loaded Successfully

#### Check Load Status

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

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

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

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

#### 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**.
2. Enter the source map URL in the textbox, then click **Add**.

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

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

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

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](/en/guide/debugging/lynx-devtool/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.

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



---
url: /guide/debugging/lynx-devtool/layers-panel.md
---

{`
  .full_image {
    width: 800px;
    margin: 20px;
  }
  `}

# Layers Panel

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

## Overview

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

* View page layers
* Inspect page layers

### Open the Layers Panel

To open the Layers panel, follow these steps:

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

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



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

Also, sometimes when your JavaScript code contains an TypeError:

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

With DevTool or LogBox, you shall easily recognize them.

## LogBox

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

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!



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

# Performance

## What is Performance

The topic of performance aims to discuss the issue of how to make Lynx pages faster. Performance optimization focuses on improving Lynx page speed through two core
objectives: maximizing runtime efficiency and ensuring a fluid user experience. It revolves around two core dimensions: **User Perceived Performance** and
**Application Runtime Performance**.

### User Perceived Performance

User Perceived Performance (UPP) quantifies users’ subjective judgment of a page’s responsiveness, including loading speed and interaction latency. As the primary
driver of user retention, UPP directly reflects how users experience application performance.

When network latency or insufficient system resources delay page rendering, users may abandon the page if no feedback mechanism (e.g., loading indicators) confirms ongoing progress.
To address this, displaying loading animations, progress bars, or other visual components can maintain user engagement. These elements reassure users that the
application is still functioning smoothly during the wait, thereby reducing bounce rates.

Improving user-perceived performance is highly beneficial for increasing user retention. However, since user perceived performance is subjective, accurately measuring it
can be challenging and complex. The [Performance API](/api/lynx-api/performance-api.md) provides metrics to help evaluate user-perceived performance. For more details,
refer to the [Evaluating User Perceived Performance](/guide/performance/evaluating-performance.md#evaluating-user-perceived-performance).

### Application Runtime Performance

Application Runtime Performance (ARP) measures quantifiable metrics for page loading and rendering speeds, forming the technical basis for user experience. ARP tracks
time spent in critical stages (e.g., initialization, resource loading) and directly determines how quickly content becomes visible.

Suboptimal ARP manifests as prolonged resource loading or rendering delays, resulting in extended wait time before content becomes interactive. Pages that load slowly
or are unresponsive can lead users to abandon further browsing.

ARP Analysis identifies bottlenecks by profiling time spent in key stages (initialization, resource loading, rendering pipelines). Developers can then implement
optimizations such as resource preloading, incremental data streaming, or task scheduling logic refinements to enhance runtime efficiency. For more details, refer to the
[Evaluating Application Runtime Performance](/guide/performance/evaluating-performance.md#evaluating-application-runtime-performance).



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

# Evaluating Performane

The performance of the Lynx page can determine users' perceptions of your application. Lynx provides the [Performance API](/api/lynx-api/performance-api.md)
to help you monitor the status of the page and accurately measure its performance during operation.

## Evaluating User Perceived Performance

It is critical to understand that **User Perceived Performance (UPP)** reflects users' subjective experience of page responsiveness. When opening a page, users typically expect
immediate content visibility rather than waiting through a blank screen. To enhance this perception, two fundamental principles apply: **Show Content Early** and **Quick Response**.

* Show Content Early: While loading a page, prioritize displaying partial content (e.g., skeleton screens, loading animations) instead of waiting for full data readiness.
  This reduces perceived wait time by providing immediate visual feedback.

* Quick Response: When user actions trigger operations that take time (such as searching or image processing), display a loading animation immediately. Although
  this doesn't change the actual completion time, it gives users the impression that the page responded timely to their actions.

These principles reduce user abandonment caused by perceived unresponsiveness. However, since UPP involves complex subjective experiences, it's challenging to rely on a single
metric for evaluation. Instead, a comprehensive assessment using multiple metrics provided by the [Performance API](/api/lynx-api/performance-api.md) is necessary:

* [First Contentful Paint (FCP)](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md): Time to first content rendering completion.

* [Actual First Meaningful Paint (ActualFMP)](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md): Time to rendering of truly meaningful content.

Based on the aforementioned metrics, if a page can immediately display primary content after loading (LoadBundle) without requiring additional data fetches to render,
prioritize optimizing *FCP*.

![First Frame Direct Render Process](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/first-render-without-network.png "First Frame Direct Render Process")

Conversely, if page rendering depends on additional data — such as asynchronous fetches via network requests or local file reads — to achieve "actual" content display,
you can [mark the Lynx pipeline](/guide/performance/timing-flag.md) to track this critical data update. By annotating the [Lynx Pipeline](/guide/spec.md#lynx-pipeline), developers can track critical data
updates and measure the resulting *ActualFMP*. Unlike scenarios without data dependencies, FCP in such cases may only show non-meaningful UI states (e.g., loading animations or skeleton screens).

![First Frame Render Process with Network Requests](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/first-render-with-network.png "First Frame Render Process with Network Requests")

This highlights a conflict: rendering real data requires additional processing time, which contradicts the goal of improving UPP. To optimize perceived performance,
prioritize static or preloaded content for the initial screen, while deferring network-dependent content to subsequent updates. Although this approach may
increases total data transfer, it significantly enhances user perceived performance by rendering meaningful content earlier.

## Evaluating Application Runtime Performance

While perceived speed (UPP) drives user satisfaction, **Application Runtime Performance (ARP)** determines technical efficiency in resource preparation and rendering.

ARP evaluation focuses on two phases: **initialize** and **render**. Both phases dictate how quickly users can interact with the application. Poor performance may
cause users to abandon accessing the page content or even be unable to access the content at all.

### Initialize

From the moment a user clicks a link to the display of a new page, an application needs to complete preparatory tasks, including initializing the page container and
preparing the [TemplateBundle](/guide/spec.md#template-bundle).

The initialization phase includes three key steps: [Container](/guide/spec.md#container) setup, [LynxView](/guide/spec.md#lynxview①)
creation, and [Background Thread Runtime](/guide/spec.md#background-thread-runtime) preparation. The [Performance API](/api/lynx-api/performance-api.md) provides
[`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md), [`InitLynxviewEntry`](/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md),
and [`InitBackgroundRuntimeEntry`](/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md) to describe these key moments. You can
combine these performance entries to analyze the entire initialization phase.

![All Initialization Phase](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/all-init-process.png "All Initialization Phase")

Although these preparations occur before the page rendering, their performance directly impacts the user experience. Slow initialization delays rendering, increasing user
wait time and negatively impacting perceived performance. To minimize loading time as much as possible, you can advance these initialization tasks by using local caching,
preloading TemplateBundle, and pre-creating LynxView, ensuring immediate response.

### Render

The rendering phase begins post-load and directly controls content visibility speed. To manage each step precisely, Lynx uses the Lynx pipeline to divide the rendering
process into several crucial stages. The [Performance API](/api/lynx-api/performance-api.md) provides the
[`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) interface to record and analyze the specific timing of these stages.

With `PipelineEntry`, you can access detailed timing data during the page rendering process, such as main thread script execution time, style computation time, and layout
computation time. These detailed timing metrics help identify performance bottlenecks, enabling targeted optimization efforts.

![Lynx Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/pipeline-entry.png "Lynx Pipeline")

Understanding and tracking the actual performance of a page is critical for improving the user experience. By utilizing specific performance metrics, you can identify which
stages are causing delays and implement optimization strategies to ensure users see a complete, interactive page as quickly as possible. This monitoring and optimization can
significantly reduce user waiting time and enhance the overall smoothness of an application.

## Building Custom Performance Metrics

Custom performance metrics align with specific business objectives. Usage of the [Performance API](/api/lynx-api/performance-api.md) is not restricted to analyzing
page performance using built-in metrics. You can flexibly combine key moments of different [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md) to build a set
of performance metrics tailored to your application.

For example, if you want to focus on the delay between the end of the first-frame rendering and the end of the first significant data updates. You can combine
[`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 calculate a new performance metric `waitingDuration` like the following code. This metric can help you monitor the speed of network requests, file reads, and other
behaviors, pinpointing the reasons for deteriorating page performance.

![waiting duration](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/custom-metric-waitingduration.png)




---
url: /guide/performance/timing-flag.md
---

# Marking Lynx Pipeline

The [Lynx Pipeline](/guide/spec.md#lynx-pipeline) defines the complete process from rendering trigger to display on the screen. If you are concerned about the performance of the rendering process for certain key components, you can mark the Lynx Pipeline that renders them by setting the `__lynx_timing_flag` attribute. This allows you to monitor the performance of that specific Lynx Pipeline.

When a marked Lynx Pipeline execution is completed and the screen display is refreshed, a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) performance event is generated. You can retrieve this event using the [`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 the `PerformanceObserver` callback.
* When the value of the `__lynx_timing_flag` attribute is `__lynx_timing_actual_fmp`, an additional [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md) performance event will be generated.

## Usage Example

1. **Marking the Node**: Set the `__lynx_timing_flag` attribute on the target component. When the node finishes rendering, the framework will automatically collect performance data for its Lynx Pipeline.
2. **Getting Data**: Register an observer using [`lynx.performance.createObserver()`](/api/lynx-api/lynx/lynx-performance.md#createobserver) to obtain relevant performance data (`PipelineEntry`).



## Important Notes

### 1. Multiple Components with Same Timing Flag

```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 displayed component will be counted:

1. Calculate the `ActualFMP` metric and send a [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).

2. Send a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

If you want to track the timing of both components completing rendering, using different \_\_lynx\_timing\_flag values.

### 2. Re-rendering Same Component

```ts
export default function App() {
  return (
    <view className="container">
      {data.needShow &&
        <text __lynx_timing_flag="__lynx_timing_actual_fmp">
          {data.msg}
        </text>
      }
    </view>
  );
}
```

In this case, only the Lynx Pipeline data of the first displayed instance of the component will be counted:

1. Calculate the `ActualFMP` metric and send a [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).

2. Send a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

If you want to perceive the rendering performance of the component with each data update, you can use data-driven flags 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




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

{`
  graph TB
    subgraph Bundle["🎯 Bundle"]
        B10["Engine Version 3.3"]
    end
    subgraph Engine["⚙️ Lynx Engine"]
        E12["Version 3.5"]
        E11["Version 3.4"]
        E10["Version 3.3"]
        E09["Version 3.2"]
    end
    B10 -.->|❌ Not Supported| E09
    B10 ==>|✅ Can Run| E10
    B10 ==>|✅ Can Run| E11
    B10 ==>|✅ Can Run| E12
    %% Node styles
    style E12 fill:#2b5a83,stroke:#4a90e2,stroke-width:3px,rx:10px
    style E11 fill:#2b5a83,stroke:#4a90e2,stroke-width:3px,rx:10px
    style E10 fill:#2b5a83,stroke:#4a90e2,stroke-width:3px,rx:10px
    style E09 fill:#2b5a83,stroke:#4a90e2,stroke-width:2px,rx:10px,stroke-dasharray:5,5
    style B10 fill:#2d5a1e,stroke:#7ed321,stroke-width:3px,rx:10px
    %% Subgraph styles
    style Bundle fill:transparent,stroke:#7ed321,stroke-width:2px,rx:10px
    style Engine fill:transparent,stroke:#4a90e2,stroke-width:2px,rx:10px
    %% Default styles
    classDef default fill:#23272f,color:#ccc,font-family:system-ui
    %% Connection line label styles
    linkStyle default stroke-width:2px
  `}

When a Bundle needs to run on multiple Lynx Engine versions, its [`engineVersion`] must be lower than all Lynx Engine versions.

When running multiple Bundles on a single Lynx Engine version, each Bundle can set different [`engineVersion`]s, but none can be greater than the Lynx Engine version.

### Version Incompatibility Handling

If you try to run a Bundle on a lower version of the Lynx Engine, a Fatal level error with code [10204](/api/errors/error-code.md#subcode-10204) will occur, and the rendering process will stop. This mechanism prevents potential runtime issues caused by version incompatibility.

### Configuring Engine Version

The [`engineVersion`] is a string containing two version numbers, and you can specify it in your configuration file:

```js title="lynx.config.js"
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReactLynx({
      engineVersion: '3.2',
    }),
  ],
});
```

## Upgrading Lynx Engine

As Lynx Engine evolves, new features are added and some features may be deprecated. Their compatibility is also managed by [`engineVersion`].

### New Features

Some new features ***will not*** affect existing Bundles, but if [`engineVersion`] is lower than the version where they were introduced, runtime detection is needed, for example:

```js
// Detect if `lynx.newlyAddedMethod` can be called
if (lynx.newlyAddedMethod) {
  lynx.newlyAddedMethod();
}
```

While some new features cannot run on lower versions of the Lynx Engine at all, so they will only be enabled when [`engineVersion`] is greater than or equal to the corresponding version.

### Deprecated Features

Some features may be deprecated during iteration, and their behavior may change when a higher [`engineVersion`] is set.

* If only the Lynx Engine version is upgraded without upgrading the Bundle's [`engineVersion`], there will be no compatibility issues
* If both Lynx Engine and Bundle's [`engineVersion`] are upgraded, you need to read the CHANGELOG to ensure there are no unexpected behavior changes

## Compatibility Table

Lynx provides compatibility tables for each API, built-in component, and CSS property. Here's an example for the [`gap`](/api/css/properties/gap.md) property:



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

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

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



---
url: /guide/scripting-runtime/index.md
---

# JavaScript Runtime

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



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

```jsx {1,6,10}
const { Component } = require('@lynx-js/react'); // can require npm packages

export default App extends Component {
  constructor(props) {
    super(props);
    const common = require('./common.js'); // can require relative path
    common.hello('world');
  }
  componentDidMount() {
    const common = require('./common.js'); // can require relative path
    common.goodbye('world');
  }
  render() {
    return <view><text>Hello, world!</text></view>;
  }
}
```

:::tip

* `require` can be anywhere in your code, not required to be at top.

* `require` will **synchronously** execute the target module.

* `require` will cache the returned object. Multiple `require` to the same path will return the **same** value. e.g:

```js
require('foo') === require('foo'); // true
```

:::

### ESModule

ESModule uses `import` to import a module. Uses `export` to export a module.
`import` and `export` must be placed at the top level of source file.

ESModule can also use `import()` to dynamically import a module.

```js title="utils.js"
export function getAge() {
  return 11;
}

export default function (add1, add2) {
  return add1 + add2;
}
```

```jsx {1-2,8,13}
import { Component } from '@lynx-js/react'; // can import npm packages
import { capitalize } from 'lodash';

export default App extends Component {
  constructor(props) {
    super(props);
    // can dynamic import relative path
    import('./utils.js').then(utils => {
      capitalize(utils.getSum());
    });
  }
  async componentDidMount() {
    const utils = await import('./utils.js'); // can dynamic import relative path
    utils.getAge();
  }
  render() {
    return <view><text>Hello, world!</text></view>;
  }
}
```



---
url: /guide/scripting-runtime/main-thread-runtime.md
---

# Main Thread Runtime

## [PrimJS](https://github.com/lynx-family/primjs)

The main thread uses PrimJS as the runtime engine. PrimJS is a lightweight, high-performance JavaScript engine designed specifically for Lynx. PrimJS is built on top of [QuickJS](https://bellard.org/quickjs/) and offers a much better performance and development experience than QuickJS.

Meanwhile, PrimJS provides a high-performance FFI capability, which can encapsulate the Lynx object as a JS object and return it to the FFI caller at low cost, which has obvious performance advantage over the traditional FFI. However, this type of JS object is not an Object Model, Lynx engine can not bind setter getter methods to this object, it can only provide FFI to pass it as a parameter to realize similar functions.

## [Element PAPI](/api/engine/element-api.md) Bindings

In order to achieve high performance, the Element PAPI provided in the main thread runtime is based on the above approach. Since ReactLynx developers don't need to manipulate Element directly in most scenarios, this limitation of high-performance FFI doesn't degrade the experience.

If developers need to operate Element directly, we provide the [main-thread-element](/api/lynx-api/main-thread/main-thread-element.md) based on the Element PAPI to improve the development experience.

## [Lynx API](/api/lynx-api/main-thread.md) Bindings

Because of the special nature of the main thread, we only provide Lynx APIs in the main thread that do not affect rendering, which are a subset of the background thread APIs.

## Runtime Script Format

For performance optimization, the main thread scripts use the bytecode format compiled by PrimJS. This format avoids the parsing of scripts at runtime, and the bytecode format can be loaded about four times faster than normal text format scripts.



---
url: /guide/use-native-modules.md
---



# Native Modules

When developing Lynx applications, you may encounter scenarios where you need to interact with native platform APIs not covered by Lynx. Or, you might want to reuse existing native platform code in your Lynx application. Regardless of the reason, you can use [**Native Modules**](/guide/spec.md#nativemodules) to seamlessly connect your JavaScript code with native code, allowing you to call native platform functions and APIs from your JavaScript code. The following will detail how to write a native module.

The basic steps for writing a native module are as follows:

1. Use TypeScript to **declare your typed interface specification**.
2. Use your interface specification to **write your Lynx application code**.
3. Follow your interface specification to **write your native platform code** and connect your native code to the Lynx runtime environment.

Next, this guide will demonstrate these steps through an example of building a native module.

:::info
Currently, native modules can only be used in [Background Thread Scripting](/guide/spec.md#background-thread-scripting).
:::

## Local Persistent Storage Module

This guide aims to show you how to write a local persistent storage module that enables your Lynx application to use JavaScript code to store data persistently locally.

To implement local persistent storage on mobile devices, you need to use the native APIs of Android and iOS:

* Android: [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences)
* iOS: [NSUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults)

### 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): string | null;
    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.

### Write Your Native Platform Code

Now, you can start writing the native platform code.

import { Steps, Tabs, Tab, PackageManagerTabs } from '@theme'
import { CodeFold } from '@lynx'

#### Prepare Your Xcode Project

First, follow the [Build Lynx Explorer for iOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) guide to create a Lynx Explorer project locally and open it with Xcode.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step1.png)

Next, right-click on the `modules` folder in the Lynx Explorer project and select `New File...` to create the header and source files for the native module.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step2.png)

Then, use the `Cocoa Touch Class` template.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step3.png)

Name the class `NativeLocalStorageModule`. You can choose to create it in either `Objective-C` or `Swift`. Then click `Next` to complete the file creation.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step4.png)

#### Implement Your Native Module

:::info
You need to implement an additional static method `name` in the native module to return the exported name of your native module. Also, implement an additional static method `methodLookup` in the native module to map the names of the methods to be exported to their corresponding selectors.
:::

```objective-c {6} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/NativeLocalStorageModule.h"

#import <Foundation/Foundation.h>
#import <Lynx/LynxModule.h>

NS_ASSUME_NONNULL_BEGIN

@interface NativeLocalStorageModule : NSObject <LynxModule>

@end

NS_ASSUME_NONNULL_END

```

```objective-c {18-20,22-27} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/NativeLocalStorageModule.m"
#import "NativeLocalStorageModule.h"

@interface NativeLocalStorageModule()
@property (strong, nonatomic) NSUserDefaults *localStorage;
@end

@implementation NativeLocalStorageModule

static NSString *const NativeLocalStorageKey = @"MyLocalStorage";

- (instancetype)init {
    if (self = [super init]) {
        _localStorage = [[NSUserDefaults alloc] initWithSuiteName:NativeLocalStorageKey];
    }
    return self;
}

+ (NSString *)name {
    return @"NativeLocalStorageModule";
}

+ (NSDictionary<NSString *, NSString *> *)methodLookup {
    return @{
        @"setStorageItem" : NSStringFromSelector(@selector(setStorageItem:value:)),
        @"getStorageItem" : NSStringFromSelector(@selector(getStorageItem:)),
        @"clearStorage" : NSStringFromSelector(@selector(clearStorage))
    };
}

- (void)setStorageItem:(NSString *)key value:(NSString *)value {
    [self.localStorage setObject:value forKey:key];
}

- (NSString*)getStorageItem:(NSString *)key {
    NSString *value = [self.localStorage stringForKey:key];
    return value;
}

- (void)clearStorage {
    NSDictionary *keys = [self.localStorage dictionaryRepresentation];
    for (NSString *key in keys) {
        [self.localStorage removeObjectForKey:key];
    }
}

@end

```

:::tip
Lynx Explorer is a project built with Objective-C. If you wish to implement a native module with Swift, please refer to [Importing Objective-C into Swift](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift) to import the required Lynx header file `LynxModule.h`.
:::

```swift title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/LynxExplorer-Bridging-Header.h"

//
//  Use this file to import your target's public headers that you would like to expose to Swift.
//

#import <Lynx/LynxModule.h>


```

```swift {6-8,10-16} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/NativeLocalStorageModule.swift"

import Foundation

@objcMembers
public final class NativeLocalStorageModule: NSObject, LynxModule {

    @objc public static var name: String {
        return "NativeLocalStorageModule"
    }

    @objc public static var methodLookup: [String : String] {
        return [
            "setStorageItem": NSStringFromSelector(#selector(setStorageItem(_:value:))),
            "getStorageItem": NSStringFromSelector(#selector(getStorageItem(_:))),
            "clearStorage": NSStringFromSelector(#selector(clearStorage))
        ]
    }

    private let localStorage: UserDefaults
    private static let storageKey = "MyLocalStorage"

    @objc public init(param: Any) {
      guard let suite = UserDefaults(suiteName: NativeLocalStorageModule.storageKey) else {
          fatalError("Failed to initialize UserDefaults with suiteName: \(NativeLocalStorageModule.storageKey)")
      }
      localStorage = suite
      super.init()
    }

    @objc public override init() {
        guard let suite = UserDefaults(suiteName: NativeLocalStorageModule.storageKey) else {
            fatalError("Failed to initialize UserDefaults with suiteName: \(NativeLocalStorageModule.storageKey)")
        }
        localStorage = suite
        super.init()
    }

    @objc func setStorageItem(_ key: String, value: String) {
        localStorage.set(value, forKey: key)
    }

    @objc func getStorageItem(_ key: String) -> String? {
        return localStorage.string(forKey: key)
    }

    @objc func clearStorage() {
        localStorage.dictionaryRepresentation().keys.forEach {
            localStorage.removeObject(forKey: $0)
        }
    }

}

```

Next, you need to register your native module into the Lynx runtime environment.

Add the following registration code to the `setupLynxEnv` method in the `explorer/darwin/ios/lynx_explorer/LynxExplorer/LynxInitProcessor.m` file of the Lynx Explorer project to register your native module with the global configuration of the Lynx runtime environment.

```objective-c {7} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/LynxInitProcessor.m"

#import "NativeLocalStorageModule.h"

- (void)setupLynxEnv {
  // ...

  // register global JS module
  [globalConfig registerModule:NativeLocalStorageModule.class];

  // ...
}


NS_ASSUME_NONNULL_END

```

:::tip
Lynx Explorer is a project built with Objective-C. If you want to use Swift native modules in Objective-C files, please refer to [Importing Swift into Objective-C](https://developer.apple.com/documentation/swift/importing-swift-into-objective-c) to generate and import the `LynxExplorer-Swift.h` header file.
:::

```objective-c {7} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/LynxInitProcessor.m"

#import "LynxExplorer-Swift.h"

- (void)setupLynxEnv {
  // ...

  // register global JS module
  [globalConfig registerModule:NativeLocalStorageModule.class];

  // ...
  }

NS_ASSUME_NONNULL_END

```

#### Run Your Code

Once you've prepared everything, you can now build and run your code.

First, follow the [Build and Run iOS Lynx Explorer](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios#build-ios-app) guide to build Lynx Explorer and install it on your phone.

Next, refer to the [Install Dependencies & Start the Development Server](/en/start/quick-start.md#Installation) guide to install dependencies and start the development server in the root directory of your Lynx project.

Install dependencies:

Start the development server:

You'll see a QR code and an artifact link in the console. Use Lynx Explorer to scan the QR code or enter the artifact link to open your Lynx page.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-demo-ios-en.gif)

import { Steps, Tabs, Tab, PackageManagerTabs } from '@theme'
import { CodeFold } from '@lynx'

First, follow the [Build Lynx Explorer for Android](https://github.com/lynx-family/lynx/tree/develop/explorer/android) guide to create a Lynx Explorer project locally.

Next, create a new `NativeLocalStorageModule.java` or `NativeLocalStorageModule.kt` file in the `explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/` path of the Lynx Explorer project. Then, inherit from `LynxModule` to implement the `NativeLocalStorageModule` native module.

:::info
You need to add the `@LynxMethod` annotation to the methods that need to be exported in the native module.
:::

```java {21,29,36} title="explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/NativeLocalStorageModule.java"
package com.lynx.explorer.modules;

import android.content.Context;
import android.content.SharedPreferences;

import com.lynx.jsbridge.LynxMethod;
import com.lynx.jsbridge.LynxModule;
import com.lynx.tasm.behavior.LynxContext;

public class NativeLocalStorageModule extends LynxModule {
private static final String PREF_NAME = "MyLocalStorage";
public NativeLocalStorageModule(Context context) {
super(context);
}

Context getContext() {
LynxContext lynxContext = (LynxContext) mContext;
return lynxContext.getContext();
}

@LynxMethod
public void setStorageItem(String key, String value) {
SharedPreferences sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
SharedPreferences.Editor editor = sharedPreferences.edit();
editor.putString(key, value);
editor.apply();
}

@LynxMethod
public String getStorageItem(String key) {
SharedPreferences sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
String value = sharedPreferences.getString(key, null);
return value;
}

@LynxMethod
public void clearStorage() {
SharedPreferences sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
SharedPreferences.Editor editor = sharedPreferences.edit();
editor.clear();
editor.apply();
}
}

```

```kotlin {16,24,30} title="explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/NativeLocalStorageModule.kt"

package com.lynx.explorer.modules

import android.content.Context
import com.lynx.jsbridge.LynxMethod
import com.lynx.jsbridge.LynxModule
import com.lynx.tasm.behavior.LynxContext

class NativeLocalStorageModule(context: Context) : LynxModule(context) {
  private val PREF_NAME = "MyLocalStorage"

  private fun getContext(): Context {
    val lynxContext = mContext as LynxContext
    return lynxContext.getContext()
  }

  @LynxMethod
  fun setStorageItem(key: String, value: String) {
    val sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE)
    val editor = sharedPreferences.edit()
    editor.putString(key, value)
    editor.apply()
  }

  @LynxMethod
  fun getStorageItem(key: String): String? {
    val sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE)
    return sharedPreferences.getString(key, null)
  }

  @LynxMethod
  fun clearStorage() {
    val sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE)
    val editor = sharedPreferences.edit()
    editor.clear()
    editor.apply()
  }
}

```

Next, you need to register your native module with the Lynx runtime environment.

Add the following registration code to the `Init` method in the `explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/LynxModuleAdapter.java` file of the Lynx Explorer project to register your native module with the Lynx runtime environment. Here, you need to specify the name of the native module you are exporting, which must be consistent with your interface specification.

```java {4} title="explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/LynxModuleAdapter.java"

  public void Init(Context context) {
    // ......

    LynxEnv.inst().registerModule("NativeLocalStorageModule", NativeLocalStorageModule.class);

    // ......
  }

```

After preparing everything, you can now build and run your code.

First, follow the [Compile and Run Android Lynx Explorer](https://github.com/lynx-family/lynx/tree/develop/explorer/android#compile-and-run) guide to build Lynx Explorer from source code and install it on your phone.

Then, refer to the [Install Dependencies & Start the Development Server](/en/start/quick-start.md#Installation) guide to install dependencies and start the development server in the root directory of your Lynx project.

Install dependencies:

Start the development server:

You will see a QR code in the console. Use Lynx Explorer to scan the QR code to open the page.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-demo-android-en.gif)

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)                                     |
| --------------- | ------------------------------------------------- | ------------------------------------------------- |
| `null`          | `nil`                                             | `null`                                            |
| `undefined`     | `nil`                                             | `null`                                            |
| `boolean`       | `BOOL` (or `NSNumber` when used inside objects)   | `boolean` (or `Boolean` when used inside objects) |
| `number`        | `double` (or `NSNumber` when used inside objects) | `double` (or `Number` when used inside objects)   |
| `string`        | `NSString`                                        | `String`                                          |
| `BigInt`        | `NSString`                                        | `long` (or `Number` when used inside objects)     |
| `ArrayBuffer`   | `NSData`                                          | `byte[]`                                          |
| `object`        | `NSDictionary`                                    | `com.lynx.react.bridge.ReadableMap`               |
| `array`         | `NSArray`                                         | `com.lynx.react.bridge.ReadableArray`             |
| Callback `()=>` | block `void (^)(id)`                              | `com.lynx.react.bridge.Callback`                  |



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



The implementation of custom native elements can be broken down into several steps, including: declaring and registering elements, creating native views, handling styles and properties, event binding, etc. Let's take a simple custom input element `<input>` as an example to briefly introduce the implementation process of custom elements.

The complete implementation can be found in the [LynxExplorer/input module](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios/lynx_explorer/LynxExplorer/input). You can compile and run the [LynxExplorer sample project](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) to preview element behavior in real-time.

### Declare and Register Elements

#### Declare Custom Elements

A declared custom element needs to inherit from `LynxUI`. Below is the implementation of the `<input>` element:

```objc title="LynxExplorerInput.h" {1,11}

#import <Lynx/LynxUI.h>

NS_ASSUME_NONNULL_BEGIN

@interface LynxTextField : UITextField

@property(nonatomic, assign) UIEdgeInsets padding;

@end

@interface LynxExplorerInput : LynxUI <LynxTextField *> <UITextFieldDelegate>

@end

NS_ASSUME_NONNULL_END
```

```objc title="LynxExplorerInput.m"

#import "LynxExplorerInput.h"

@implementation LynxExplorerInput

//...

@end



@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```

#### Register Custom Element

Elements can be registered in two ways: globally and locally.

##### Global Registration

Globally registered elements can be shared across multiple `LynxView` instances.

```objc title="LynxExplorerInput.m" {2,6}

#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("input")

@end



@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```

##### Local Registration

Locally registered elements are only applicable to the current `LynxView` instance.

```objc {7}
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxView.h>

  LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
    builder.config =
        [[LynxConfig alloc] initWithProvider:[LynxEnv sharedInstance].config.templateProvider];
    [builder.config registerUI:[LynxExplorerInput class] withName:@"input"];
  }];
```

Where `"input"` corresponds to the tag name in the front-end DSL. When Lynx Engine parses this tag, it will look for the registered native element and create an instance.

### Create Native `View` Instance

Each custom element needs to implement the `createView` method, which returns a corresponding native `View` instance.

Here is the implementation for the `<input>` element:

```objc title="LynxExplorerInput.m" {8-13}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("input")

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  return textField;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```

### Handle Front-End Style and Property Updates

You can use the `LYNX_PROP_SETTER` macro to listen for property changes passed from the front end and update the native view. For example, handling the `value` property of the `<input>` element:

```objc title="LynxExplorerInput.m" {3,9-11}

#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("input")

LYNX_PROP_SETTER("value", setValue, NSString *) {
    self.view.text = value;
}

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  return textField;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```

### Handle Layout Information (Optional)

#### Handle Lynx Engine Layout Results

Typically, Lynx Engine automatically calculates and updates the `View` layout information, so developers do not need to manually handle this. However, in some special cases, such as when additional adjustments to the `View` are required, you can obtain the latest layout information in the `layoutDidFinished` callback and apply custom logic.

```objc title="LynxExplorerInput.m" {9-11}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("input")

- (void)layoutDidFinished {
  self.view.padding = self.padding;
  }

LYNX_PROP_SETTER("value", setValue, NSString \*) {
self.view.text = value;
}

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  return textField;
  }

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
  }

- (void)setPadding:(UIEdgeInsets)padding {
  \_padding = padding;
  [self setNeedsLayout];
  }

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
  }

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
  }
  @end

```

### Handle Event Binding (Optional)

In some scenarios, the front-end may need to respond to events from custom elements. For example, when the user types in the input box, the front-end might

need to capture and process the input data.

Here is an example of how to send a text input event from the `<input>` element to the front-end and how the front-end listens for the event.

#### Client-Side Event Sending

The client listens to text input callbacks from the native view, and when the text changes, it uses `[self.context.eventEmitter dispatchCustomEvent:eventInfo]` to send the event to the front-end for handling.

```objc title="LynxExplorerInput.m" {13-16,20-25,27-32}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("input")

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  [[NSNotificationCenter defaultCenter] addObserver:self
                                        selector:@selector(textFieldDidChange:)
                                        name:UITextFieldTextDidChangeNotification
                                        object:textField];
  return textField;
}

- (void)emitEvent:(NSString *)name detail:(NSDictionary *)detail {
  LynxCustomEvent *eventInfo = [[LynxDetailEvent alloc] initWithName:name
                                                          targetSign:[self sign]
                                                              detail:detail];
  [self.context.eventEmitter dispatchCustomEvent:eventInfo];
}

- (void)textFieldDidChange:(NSNotification *)notification {
  [self emitEvent:@"input"
           detail:@{
             @"value": [self.view text] ?: @"",
           }];
}

- (void)layoutDidFinished {
    self.view.padding = self.padding;
}

LYNX_PROP_SETTER("value", setValue, NSString *) {
    self.view.text = value;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```

#### Front-End DSL Event Binding

On the front-end, bind the corresponding input event to listen for and handle the text input data sent by the client.

```jsx title="App.tsx"
const handleInput = (e) => {
  const currentValue = e.detail.value.trim();
  setInputValue(currentValue);
};

<input className="input-box" bindinput={handleInput} value={inputValue} />;
```

> **Note**: The front-end DSL uses `bindxxx` for event binding, such as `bindinput` to bind the `input` event.

### Support Direct Element Manipulation (Optional)

In some cases, the front-end may need to directly manipulate custom elements via imperative APIs. You can make elements support such operations with `LYNX_UI_METHOD`.

#### Front-End Call Example

The following code shows how to use [SelectorQuery](/api/lynx-api/selector-query.md) to call the `focus` method and focus the `<input>` element:

```jsx title="App.tsx"
lynx
  .createSelectorQuery()
  .select('#input-id')
  .invoke({
    method: 'focus',
    params: {},
    success: function (res) {
      console.log('lynx', 'request focus success');
    },
    fail: function (res) {
      console.log('lynx', 'request focus fail');
    },
  })
  .exec();
```

#### Client-Side Implementation

On the client side, use `LYNX_UI_METHOD` to add a `focus` method to the custom element to handle the front-end call.

```objc title="LynxExplorerInput.m" {4,10-16}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>
#import <Lynx/LynxUIMethodProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("input")

LYNX_UI_METHOD(focus) {
    if ([self.view becomeFirstResponder]) {
        callback(kUIMethodSuccess, nil);
    } else {
        callback(kUIMethodUnknown, @"fail to focus");
    }
}

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  [[NSNotificationCenter defaultCenter] addObserver:self
                                        selector:@selector(textFieldDidChange:)
                                        name:UITextFieldTextDidChangeNotification
                                        object:textField];
  return textField;
}

- (void)emitEvent:(NSString *)name detail:(NSDictionary *)detail {
  LynxCustomEvent *eventInfo = [[LynxDetailEvent alloc] initWithName:name
                                                          targetSign:[self sign]
                                                              detail:detail];
  [self.context.eventEmitter dispatchCustomEvent:eventInfo];
}

- (void)textFieldDidChange:(NSNotification *)notification {
  [self emitEvent:@"input"
           detail:@{
             @"value": [self.view text] ?: @"",
           }];
}

- (void)layoutDidFinished {
    self.view.padding = self.padding;
}

LYNX_PROP_SETTER("value", setValue, NSString *) {
    self.view.text = value;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```

#### Method Callback Return Values

When implementing the focus method, component developers need to return a status code to the frontend to indicate whether the operation was successful. For instance, the frontend call might fail, in which case an appropriate error status should be returned so that the frontend can handle it in the `fail` callback.

Lynx Engine defines several common error codes, and developers can return the appropriate status code in the method callback:

```objc
enum LynxUIMethodErrorCode {
  kUIMethodSuccess = 0, // Succeeded
  kUIMethodUnknown, // Unknown error
  kUIMethodNodeNotFound, // Cannot find corresponding element
  kUIMethodMethodNotFound, // No corresponding method on this element
  kUIMethodParamInvalid, // Invalid method parameters
  kUIMethodSelectorNotSupported, // Selector not supported
};
```

import { Steps, Tabs, Tab } from '@theme';
import { CodeFold } from '@lynx';

### Custom Native element Implementation Process

The implementation of custom native elements involves several steps, including: declaring and registering the element, creating native views, handling styles and properties, event binding, etc. Let's take a simple custom input element `<input>` as an example to briefly introduce the implementation process of a custom element. The complete code can be viewed in [LynxExplorer](https://github.com/lynx-family/lynx/tree/develop/explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/input).

The complete implementation can be found in the [LynxExplorer/input module](https://github.com/lynx-family/lynx/tree/develop/explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/input). You can compile and run the [LynxExplorer sample project](https://github.com/lynx-family/lynx/tree/develop/explorer/android) to preview element behavior in real-time.

### Declaring and Registering the Element

#### Declare the Custom Element

The declared custom element needs to inherit from `LynxUI`.

```java title="LynxExplorerInput.java"

import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.ui.LynxUI;
import androidx.appcompat.widget.AppCompatEditText;


public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }
  //...

}

```

```kotlin title="LynxExplorerInput.kt"

import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.ui.LynxUI
import androidx.appcompat.widget.AppCompatEditText


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

   //...

}

```

#### Register the Custom Element

There are two ways to register elements: global registration and local registration.

##### Global Registration

Globally registered elements can be shared among multiple `LynxView` instances.

```java

import com.lynx.tasm.LynxEnv;
import com.lynx.tasm.behavior.Behavior;

LynxEnv.inst().addBehavior(new Behavior("input"){
      @Override
      public LynxExplorerInput createUI(LynxContext context) {
        return new LynxExplorerInput(context);
      }
    });

```

```kotlin

import com.lynx.tasm.LynxEnv
import com.lynx.tasm.behavior.Behavior

LynxEnv.inst().addBehavior(object : Behavior("input") {
    override fun createUI(context: LynxContext): LynxExplorerInput {
        return LynxExplorerInput(context)
    }
})

```

##### Local Registration

Locally registered elements are only available for the current `LynxView` instance.

```java

LynxViewBuilder lynxViewBuilder = new LynxViewBuilder();
lynxViewBuilder.addBehavior(new Behavior("input") {
      @Override
      public LynxExplorerInput createUI(LynxContext context) {
        return new LynxExplorerInput(context);
      }
    });

```

```kotlin

    val lynxViewBuilder = LynxViewBuilder()
    lynxViewBuilder.addBehavior(object : Behavior("input") {
      override fun createUI(context: LynxContext): LynxExplorerInput {
        return LynxExplorerInput(context)
      }
    })

```

Where `"input"` corresponds to the tag name in the front-end DSL. When the Lynx Engine encounters this tag, it will look for the registered native element and create an instance.

### Create the Native `View` Instance

Each custom element needs to implement the `createView` method, which returns the corresponding native `View` instance.

Here’s the implementation for the `<input>` element:

```java title="LynxExplorerInput.java" {12-17}

import android.content.Context;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.ui.LynxUI;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    //...
    return view;
  }

}


```

```kotlin title="LynxExplorerInput.kt" {9-13}

import android.content.Context
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.ui.LynxUI


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      //...
    }
  }
}

```

### Handle Front-End Style and Property Updates

You can use the `@LynxProp` annotation to listen for property changes passed from the front-end and update the native view accordingly. For example, handling the `value` property of the `<input>` element:

```java {4,13-18} title="LynxExplorerInput.java"

import android.content.Context;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    //...
    return view;
  }



}


```

```kotlin {4,15-20} title="LynxExplorerInput.kt"

import android.content.Context
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.ui.LynxUI

class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      //...
    }
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}

```

### Handle Layout Information (Optional)

#### Handle the Layout Result from the Lynx Engine

Usually, the Lynx Engine will automatically calculate and update the `View` layout information, so developers don’t need to handle this manually. However, in some special cases, such as when extra adjustments are needed for the `View`, you can retrieve the latest layout information in the `onLayoutUpdated` callback and apply custom logic.

```java title="LynxExplorerInput.java" {13-21}

import android.content.Context;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  public void onLayoutUpdated() {
    super.onLayoutUpdated();
    int paddingTop = mPaddingTop + mBorderTopWidth;
    int paddingBottom = mPaddingBottom + mBorderBottomWidth;
    int paddingLeft = mPaddingLeft + mBorderLeftWidth;
    int paddingRight = mPaddingRight + mBorderRightWidth;
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    //...
    return view;
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }

}


```

```kotlin title="LynxExplorerInput.kt" {10-17}

import android.content.Context
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.ui.LynxUI


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun onLayoutUpdated() {
    super.onLayoutUpdated()
    val paddingTop = mPaddingTop + mBorderTopWidth
    val paddingBottom = mPaddingBottom + mBorderBottomWidth
    val paddingLeft = mPaddingLeft + mBorderLeftWidth
    val paddingRight = mPaddingRight + mBorderRightWidth
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom)
  }

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      //...
    }
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}



```

### Event Binding

Event handling in native elements is usually done using the `@LynxEvent` annotation, which binds events between the front-end and native elements. For example, let’s implement a custom `onChange` event for the `<input>` element:

```java title="LynxExplorerInput.java" {2-3,8-10,14-22,27-43}
import android.content.Context;
import android.text.Editable;
import android.text.TextWatcher;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;
import com.lynx.tasm.event.LynxCustomEvent;
import java.util.HashMap;
import java.util.Map;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  private void emitEvent(String name, Map<String, Object> value) {
    LynxCustomEvent detail = new LynxCustomEvent(getSign(), name);
    if (value != null) {
      for (Map.Entry<String, Object> entry : value.entrySet()) {
        detail.addDetail(entry.getKey(), entry.getValue());
      }
    }
    getLynxContext().getEventEmitter().sendCustomEvent(detail);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    view.addTextChangedListener(new TextWatcher() {
      @Override
      public void afterTextChanged(Editable s) {
        emitEvent("input", new HashMap<String, Object>() {
          {
            put("value", s.toString());
          }
        });
      }

      @Override
      public void beforeTextChanged(CharSequence s, int start, int count, int after) {}

      @Override
      public void onTextChanged(CharSequence s, int start, int before, int count) {
      }
    });
    return view;

  }

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  public void onLayoutUpdated() {
    super.onLayoutUpdated();
    int paddingTop = mPaddingTop + mBorderTopWidth;
    int paddingBottom = mPaddingBottom + mBorderBottomWidth;
    int paddingLeft = mPaddingLeft + mBorderLeftWidth;
    int paddingRight = mPaddingRight + mBorderRightWidth;
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom);
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }

}


```

```kotlin title="LynxExplorerInput.kt" {2-3,8,15-23,27-33}

import android.content.Context
import android.text.Editable
import android.text.TextWatcher
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.ui.LynxUI
import com.lynx.tasm.event.LynxCustomEvent


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      addTextChangedListener(object : TextWatcher {
        override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}

        override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {}

        override fun afterTextChanged(s: Editable?) {
          emitEvent("input", mapOf("value" to (s?.toString() ?: "")))
        }
      })
    }
  }

  private fun emitEvent(name: String, value: Map<String, Any>?) {
    val detail = LynxCustomEvent(sign, name)
    value?.forEach { (key, v) ->
      detail.addDetail(key, v)
    }
    lynxContext.eventEmitter.sendCustomEvent(detail)
  }


  override fun onLayoutUpdated() {
    super.onLayoutUpdated()
    val paddingTop = mPaddingTop + mBorderTopWidth
    val paddingBottom = mPaddingBottom + mBorderBottomWidth
    val paddingLeft = mPaddingLeft + mBorderLeftWidth
    val paddingRight = mPaddingRight + mBorderRightWidth
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom)
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}


```

### Front-End DSL Event Binding

On the front-end, you need to bind the relevant input events for the text box. With the following code, the front-end will listen for events sent by the client and process the input data as needed.

```jsx title="App.tsx"
const handleInput = (e) => {
  const currentValue = e.detail.value.trim();
  setInputValue(currentValue);
};

<input className="input-box" bindinput={handleInput} value={inputValue} />;
```

> **Note**: Front-end DSL uses `bindxxx` for event binding, such as `bindinput` for binding the `input` event.

### Supporting Direct Element Manipulation (Optional)

In some cases, the front-end may need to directly manipulate custom elements using imperative APIs. You can enable such operations on elements by using `@LynxUIMethod`.

#### Front-End Example Call

The following code demonstrates how to use the [SelectorQuery](/api/lynx-api/selector-query.md) API to call the `focus` method and make the `<input>` element gain focus:

```jsx title="App.tsx"
lynx
  .createSelectorQuery()
  .select('#input-id')
  .invoke({
    method: 'focus',
    params: {},
    success: function (res) {
      console.log('lynx', 'request focus success');
    },
    fail: function (res) {
      console.log('lynx', 'request focus fail');
    },
  })
  .exec();
```

#### Client-Side Implementation

On the client side, you need to add the `focus` method to your custom element using `@LynxUIMethod`, ensuring it can correctly handle the front-end call.

```java title="LynxExplorerInput.java" {4,6-7,10-11,20-24,26-37}
import android.content.Context;
import android.text.Editable;
import android.text.TextWatcher;
import android.view.inputmethod.InputMethodManager;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.react.bridge.Callback;
import com.lynx.react.bridge.ReadableMap;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.LynxUIMethod;
import com.lynx.tasm.behavior.LynxUIMethodConstants;
import com.lynx.tasm.behavior.ui.LynxUI;
import com.lynx.tasm.event.LynxCustomEvent;

import java.util.HashMap;
import java.util.Map;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  private boolean showSoftInput() {
    InputMethodManager imm = (InputMethodManager) getLynxContext().getSystemService(Context.INPUT_METHOD_SERVICE);
    return imm.showSoftInput(mView,
      InputMethodManager.SHOW_IMPLICIT, null);
  }

  @LynxUIMethod
  public void focus(ReadableMap params, Callback callback) {
    if (mView.requestFocus()) {
      if (showSoftInput()) {
        callback.invoke(LynxUIMethodConstants.SUCCESS);
      } else {
        callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to show keyboard");
      }
    } else {
      callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to focus");
    }
  }

  private void emitEvent(String name, Map<String, Object> value) {
    LynxCustomEvent detail = new LynxCustomEvent(getSign(), name);
    if (value != null) {
      for (Map.Entry<String, Object> entry : value.entrySet()) {
        detail.addDetail(entry.getKey(), entry.getValue());
      }
    }
    getLynxContext().getEventEmitter().sendCustomEvent(detail);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    view.addTextChangedListener(new TextWatcher() {
      @Override
      public void afterTextChanged(Editable s) {
        emitEvent("input", new HashMap<String, Object>() {
          {
            put("value", s.toString());
          }
        });
      }

      @Override
      public void beforeTextChanged(CharSequence s, int start, int count, int after) {
      }

      @Override
      public void onTextChanged(CharSequence s, int start, int before, int count) {
      }
    });
    return view;
  }

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  public void onLayoutUpdated() {
    super.onLayoutUpdated();
    int paddingTop = mPaddingTop + mBorderTopWidth;
    int paddingBottom = mPaddingBottom + mBorderBottomWidth;
    int paddingLeft = mPaddingLeft + mBorderLeftWidth;
    int paddingRight = mPaddingRight + mBorderRightWidth;
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom);
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }
}

```

```kotlin title="LynxExplorerInput.kt" {4,6-7,18-21,23-34}

import android.content.Context
import android.text.Editable
import android.text.TextWatcher
import android.view.inputmethod.InputMethodManager
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.react.bridge.Callback
import com.lynx.react.bridge.ReadableMap
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.LynxUIMethod
import com.lynx.tasm.behavior.LynxUIMethodConstants
import com.lynx.tasm.behavior.ui.LynxUI
import com.lynx.tasm.event.LynxCustomEvent


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  private fun showSoftInput(): Boolean {
    val imm = lynxContext.getSystemService(Context.INPUT_METHOD_SERVICE) as InputMethodManager
    return imm.showSoftInput(mView, InputMethodManager.SHOW_IMPLICIT, null)
  }

  @LynxUIMethod
  fun focus(params: ReadableMap, callback: Callback) {
    if (mView.requestFocus()) {
      if (showSoftInput()) {
        callback.invoke(LynxUIMethodConstants.SUCCESS)
      } else {
        callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to show keyboard")
      }
    } else {
      callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to focus")
    }
  }

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      addTextChangedListener(object : TextWatcher {
        override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}

        override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {}

        override fun afterTextChanged(s: Editable?) {
          emitEvent("input", mapOf("value" to (s?.toString() ?: "")))
        }
      })
    }
  }

  private fun emitEvent(name: String, value: Map<String, Any>?) {
    val detail = LynxCustomEvent(sign, name)
    value?.forEach { (key, v) ->
      detail.addDetail(key, v)
    }
    lynxContext.eventEmitter.sendCustomEvent(detail)
  }

  override fun onLayoutUpdated() {
    super.onLayoutUpdated()
    val paddingTop = mPaddingTop + mBorderTopWidth
    val paddingBottom = mPaddingBottom + mBorderBottomWidth
    val paddingLeft = mPaddingLeft + mBorderLeftWidth
    val paddingRight = mPaddingRight + mBorderRightWidth
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom)
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}

```

#### Method Callback Return Values

When implementing the focus method, component developers need to return a status code to the frontend to indicate whether the operation was successful. For instance, the frontend call might fail, in which case an appropriate error status should be returned so that the frontend can handle it in the `fail` callback.

Lynx Engine predefines some common error codes, and the element developer can return the appropriate status code in the method callback:

```java
enum LynxUIMethodErrorCode {
  kUIMethodSuccess, // Succeeded
  kUIMethodUnknown, // Unknown error
  kUIMethodNodeNotFound, // Cannot find corresponding element
  kUIMethodMethodNotFound, // No corresponding method on this element
  kUIMethodParamInvalid, // Invalid method parameters
  kUIMethodSelectorNotSupported, // Selector not supported
}
```

The way to customize elements in the web can directly refer to [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)

## Use your Native Element

Once you have completed the development of a custom element, you can use it just like a built-in element. Below is a simple example of using an `<input>` element:



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

You should proactively set its size constraints, when creating a LynxView on iOS.

There are two ways to set size constraints for LynxView.

* Using `updateViewportWithPreferredLayoutWidth` and `setLayoutWidthMode、setLayoutHeightMode` to set fixed or flexible sizes.
* Using `lynxviewbuilder#frame` to set fixed size.

Supported constraint modes:

```objective-c
typedef NS_ENUM(NSInteger, LynxViewSizeMode) {
  LynxViewSizeModeUndefined = 0,
  LynxViewSizeModeExact,
  LynxViewSizeModeMax
};
```

* `LynxViewSizeModeUndefined`

  LynxView's size is determined by Page content, with no parent constraints.

* `LynxViewSizeModeExact`

  LynxView's size is fixed, same as the Page element's size.

* `LynxViewSizeModeMax`

  LynxView's maximum width or height.

### Get size constraints in the `onMeasure` method.

Android system provides an [onMeasure](https://developer.android.com/reference/android/view/View#onMeasure\(int,%20int\)) for views, during which LynxView receives size constraints from its parent view.
Lynx will complete the layout of all elements and calculate the size of LynxView within the system's `onMeasure` function, and then set the correct value using [setMeasuredDimension](https://developer.android.com/reference/android/view/View#setMeasuredDimension\(int,%20int\)).

[View.MeasureSpec](https://developer.android.com/reference/android/view/View.MeasureSpec) values:

* `UNSPECIFIED`

  LynxView's size is determined by Page content, with no parent constraints.

* `EXACTLY`

  LynxView's size is fixed, same as the Page element's size.

* `AT_MOST`

  LynxView's maximum width or height.

When the content of the page needs to be re-layout, Lynx will call the system's [requestLayout](https://developer.android.com/reference/android/view/View#requestLayout\(\)), which triggers `onMeasure` to execute again.

### Preset Width and Height, Trigger Layout Early

When creating LynxView, you can preset its size constraints using `LynxViewBuilder#setPresetMeasuredSpec`, with parameters identical to`onMeasure`. This triggers layout during the [rendering pipeline](/guide/spec.md#pipeline) instead of waiting for `onMeasure`.

If a change in `measureSpec` is detected, the layout will re-trigger to ensure LynxView's size is correct.

For example, you can preset a fixed size of 400x200 with the following code:

```java
LynxViewBuilder viewBuilder = new LynxViewBuilder();
viewBuilder = viewBuilder.setPresetMeasuredSpec(View.MeasureSpec.makeMeasureSpec(400, View.MeasureSpec.EXACTLY),
        View.MeasureSpec.makeMeasureSpec(200, View.MeasureSpec.EXACTLY));

LynxView lynxview = viewBuilder.build(this);;
```

### LynxView with fixed size

### Use the `LynxViewBuilder#frame`

You can set the `frame` property size when creating LynxView, so the size of LynxView is fixed.

For example, if you want to fix the size of LynxView to 400x200, you can do it as follows:

```objective-c
   LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
       builder.frame =  CGRectMake(0, 0, 400, 200);
         ...
    }];
```

### Use `preferredLayoutWidth/preferredLayoutHeight` and `layoutWidthMode/layoutHeightMode`

For example:

```objective-c
_lynxView.layoutWidthMode = LynxViewSizeModeExact;
_lynxView.layoutHeightMode = LynxViewSizeModeExact;

_lynxView.preferredLayoutWidth = 400;
_lynxView.preferredLayoutHeight = 200;
```

As long as the outer container constraint for LynxView is `EXACTLY`, the size of LynxView will be fixed.

For example, if you want to set a 400x200 sized LynxView:

```java
//You can directly specify the size of LynxView
parentView.addView(lynxview, new ViewGroup.LayoutParams(400, 200));

//You can also fix the parent node's size and set it to MATCH_PARENT
parentView.addView(lynxview,
   new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,ViewGroup.LayoutParams.MATCH_PARENT));

```

### LynxView with flexible size

If you want LynxView to adapt its size based on its content, you can either avoid setting `LynxViewBuilder#frame`, or set `setLayoutWidth/HeightMode` to `LynxViewSizeModeUndefined` or `LynxViewSizeModeMax`.

```objective-c
_lynxView.layoutWidthMode = LynxViewSizeModeUndefined;
_lynxView.layoutHeightMode = LynxViewSizeModeUndefined;

//Alternatively, limit the width to 400 and the height to 750.
_lynxView.preferredLayoutWidth = 400;
_lynxView.preferredLayoutHeight = 750;
_lynxView.layoutWidthMode = LynxViewSizeModeMax;
_lynxView.layoutHeightMode = LynxViewSizeModeMax;
```

The layout constraints here are consistent with the Android views.

For example, setting the layout parameters for LynxView to [WRAP\_CONTENT](https://developer.android.com/reference/android/view/ViewGroup.LayoutParams#WRAP_CONTENT) will make LynxView size adapt to its content.

```java
parentView.addView(lynxview,
    new ViewGroup.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT,ViewGroup.LayoutParams.WRAP_CONTENT));
```



---
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](/en/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:

```objective-c {5}
LynxLoadMeta* meta = [LynxLoadMeta init];
// meta.url = @"";
// meta.binaryData = nil;
// meta.templateBundle = nil;
meta.initialData = __YOUR_DATA__;
// meta.loadOption = LynxLoadOptionDumpElement | LynxLoadOptionRecycleTemplateBundle;
[lynxView loadTemplate:meta];
```

```java {5}
LynxLoadMeta.Builder builder = new LynxLoadMeta.Builder();
// builder.setUrl();
// builder.setBinaryData();
// builder.setTemplateBundle();
builder.setInitialData(__YOUR_DATA__);
// builder.addLoadOption();
LynxLoadMeta meta = builder.build();
lynxView.loadTemplate(meta);
```

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

```objc {2}
LynxUpdateMeta* meta = [LynxUpdateMeta init];
meta.data = __YOUR_DATA__;
[lynxView updateData:meta];
```

```java {2}
LynxUpdateMeta.Builder builder = new LynxUpdateMeta.Builder();
builder.setUpdatedData(__YOUR_DATA__);
LynxUpdateMeta meta = builder.build();
lynxView.updateMetaData(meta);
```

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:

  ```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 both 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()`]:

```objc
LynxUpdateMeta *meta = [[LynxUpdateMeta alloc] init];

// TODO: set data and processorName

[lynxView updateData:meta];
```

```java
LynxUpdateMeta meta = new LynxUpdateMeta();

// TODO: set data and processorName

lynxView.updateMetaData(meta);
```

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



---
url: /guide/spec.md
---

{/* # Living Specification */}




---
url: /api/index.md
---




---
url: /api/rspeedy/qrcode-rsbuild-plugin.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/qrcode-rsbuild-plugin](./qrcode-rsbuild-plugin.md)

## qrcode-rsbuild-plugin package

A rsbuild plugin that print the template.js url using QRCode.

## Functions

|  Function | Description |
|  --- | --- |
|  [pluginQRCode(options)](./qrcode-rsbuild-plugin.pluginqrcode.md) | Create a rsbuild plugin for printing QRCode. |

## Interfaces

|  Interface | Description |
|  --- | --- |
|  [PluginQRCodeOptions](./qrcode-rsbuild-plugin.pluginqrcodeoptions.md) | The options for [pluginQRCode()](./qrcode-rsbuild-plugin.pluginqrcode.md)<!-- -->. |

## Type Aliases

|  Type Alias | Description |
|  --- | --- |
|  [CustomizedSchemaFn](./qrcode-rsbuild-plugin.customizedschemafn.md) | Customize the generated schema. |




---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/qrcode-rsbuild-plugin](./qrcode-rsbuild-plugin.md) &gt; [PluginQRCodeOptions](./qrcode-rsbuild-plugin.pluginqrcodeoptions.md)

## PluginQRCodeOptions interface

The options for [pluginQRCode()](./qrcode-rsbuild-plugin.pluginqrcode.md)<!-- -->.

**Signature:**

```typescript
export interface PluginQRCodeOptions 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [schema?](./qrcode-rsbuild-plugin.pluginqrcodeoptions.schema.md) |  | [CustomizedSchemaFn](./qrcode-rsbuild-plugin.customizedschemafn.md) \| undefined | _(Optional)_ Customize the generated schema. |




---
url: /api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [AddComponentElementConfig](./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](./react-rsbuild-plugin.addcomponentelementconfig.compileronly.md) |  | boolean | Whether to only add component element during compilation |




---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./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](./react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md) |  | boolean \| [AddComponentElementConfig](./react-rsbuild-plugin.addcomponentelementconfig.md) | Controls whether to add wrapper elements for components |
|  [additionalComponentAttributes](./react-rsbuild-plugin.compatvisitorconfig.additionalcomponentattributes.md) |  | Array&lt;string&gt; | Specifies additional component attributes list, these attributes will be passed to the wrapped <code>&lt;view&gt;</code> instead of the component. |
|  [componentsPkg](./react-rsbuild-plugin.compatvisitorconfig.componentspkg.md) |  | Array&lt;string&gt; | Specifies the list of component package names that need compatibility processing |
|  [darkMode?](./react-rsbuild-plugin.compatvisitorconfig.darkmode.md) |  | boolean \| DarkModeConfig | _(Optional)_ |
|  [disableDeprecatedWarning](./react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md) |  | boolean | Whether to disable deprecated warnings |
|  [newRuntimePkg](./react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md) |  | string | Specifies the new runtime package name |
|  [oldRuntimePkg](./react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md) |  | Array&lt;string&gt; | Specifies the list of old runtime package names that need compatibility processing |
|  [removeComponentAttrRegex?](./react-rsbuild-plugin.compatvisitorconfig.removecomponentattrregex.md) |  | string | _(Optional)_ Regular expression used to remove component attributes |
|  [simplifyCtorLikeReactLynx2](./react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md) |  | boolean | Whether to simplify constructor calls like ReactLynx 2 |




---
url: /api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [DefineDceVisitorConfig](./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](./react-rsbuild-plugin.definedcevisitorconfig.define.md) |  | Record&lt;string, string&gt; | 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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [ExtractStrConfig](./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](./react-rsbuild-plugin.extractstrconfig.strlength.md) |  | number | The minimum length of string literals to be extracted. |




---
url: /api/rspeedy/react-rsbuild-plugin.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md)

## react-rsbuild-plugin package

A rsbuild plugin that integrates with ReactLynx.

## Functions

|  Function | Description |
|  --- | --- |
|  [pluginReactLynx(userOptions)](./react-rsbuild-plugin.pluginreactlynx.md) | Create a rsbuild plugin for ReactLynx. |

## Interfaces

|  Interface | Description |
|  --- | --- |
|  [AddComponentElementConfig](./react-rsbuild-plugin.addcomponentelementconfig.md) | Controls whether to add wrapper elements for components |
|  [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) | The <code>compat</code> option controls compatibilities with ReactLynx2.0. |
|  [DefineDceVisitorConfig](./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](./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](./react-rsbuild-plugin.pluginreactlynxoptions.md) | Options of [pluginReactLynx()](./react-rsbuild-plugin.pluginreactlynx.md) |
|  [ShakeVisitorConfig](./react-rsbuild-plugin.shakevisitorconfig.md) | How main-thread code will be shaken. |




---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.jsx.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [jsx](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md)

## PluginReactLynxOptions interface

Options of [pluginReactLynx()](./react-rsbuild-plugin.pluginreactlynx.md)

**Signature:**

```typescript
export interface PluginReactLynxOptions 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [compat?](./react-rsbuild-plugin.pluginreactlynxoptions.compat.md) |  | Partial&lt;[CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md)<!-- -->&gt; &amp; { disableCreateSelectorQueryIncompatibleWarning?: boolean; } \| undefined | _(Optional)_ The <code>compat</code> option controls compatibilities with ReactLynx2.0. |
|  [customCSSInheritanceList?](./react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md) |  | string\[\] \| undefined | _(Optional)_ When [PluginReactLynxOptions.enableCSSInheritance](./react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md) is enabled, <code>customCSSInheritanceList</code> can control which properties are inheritable, not just the default ones. |
|  [debugInfoOutside?](./react-rsbuild-plugin.pluginreactlynxoptions.debuginfooutside.md) |  | boolean | _(Optional)_ debugInfoOutside controls whether the debug info is placed outside the template. |
|  [defaultDisplayLinear?](./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?](./react-rsbuild-plugin.pluginreactlynxoptions.definedce.md) |  | Partial&lt;[DefineDceVisitorConfig](./react-rsbuild-plugin.definedcevisitorconfig.md)<!-- -->&gt; \| undefined | _(Optional)_ Like <code>define</code> in various bundlers, but this one happens at transform time, and a DCE pass will be performed. |
|  [enableAccessibilityElement?](./react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md) |  | boolean | _(Optional)_ enableAccessibilityElement set the default value of <code>accessibility-element</code> for all <code>&lt;view /&gt;</code> elements. |
|  [enableCSSInheritance?](./react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md) |  | boolean | _(Optional)_ enableCSSInheritance enables the default inheritance properties. |
|  [enableCSSInvalidation?](./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?](./react-rsbuild-plugin.pluginreactlynxoptions.enablecssselector.md) |  | boolean | _(Optional)_ enableCSSSelector controls whether enabling the new CSS implementation. |
|  [enableICU?](./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?](./react-rsbuild-plugin.pluginreactlynxoptions.enablenewgesture.md) |  | boolean | _(Optional)_ enableNewGesture enables the new gesture system. |
|  [enableParallelElement?](./react-rsbuild-plugin.pluginreactlynxoptions.enableparallelelement.md) |  | boolean | _(Optional)_ enableParallelElement enables Threaded Element Resolution. |
|  [enableRemoveCSSScope?](./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?](./react-rsbuild-plugin.pluginreactlynxoptions.enablessr.md) |  | boolean | _(Optional)_ <code>enableSSR</code> enable Lynx SSR feature for this build. |
|  [engineVersion?](./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?](./react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md) |  | boolean | **_(ALPHA)_** _(Optional)_ Generate standalone lazy bundle. |
|  [extractStr?](./react-rsbuild-plugin.pluginreactlynxoptions.extractstr.md) |  | Partial&lt;[ExtractStrConfig](./react-rsbuild-plugin.extractstrconfig.md)<!-- -->&gt; \| boolean | _(Optional)_ Merge same string literals in JS and Lepus to reduce output bundle size. Set to <code>false</code> to disable. |
|  [firstScreenSyncTiming?](./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>&quot;immediately&quot;</code>: Transfer immediately</p><p><code>&quot;jsReady&quot;</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?](./react-rsbuild-plugin.pluginreactlynxoptions.pipelineschedulerconfig.md) |  | number | _(Optional)_ Composite configuration representing pipeline scheduling strategies, including [PluginReactLynxOptions.enableParallelElement](./react-rsbuild-plugin.pluginreactlynxoptions.enableparallelelement.md) and list batch-rendering. All newly introduced scheduling strategies will be managed by this uint64 configuration. |
|  [removeDescendantSelectorScope?](./react-rsbuild-plugin.pluginreactlynxoptions.removedescendantselectorscope.md) |  | boolean | _(Optional)_ removeDescendantSelectorScope is used to remove the scope of descendant selectors. |
|  [shake?](./react-rsbuild-plugin.pluginreactlynxoptions.shake.md) |  | Partial&lt;[ShakeVisitorConfig](./react-rsbuild-plugin.shakevisitorconfig.md)<!-- -->&gt; \| undefined | _(Optional)_ How main-thread code will be shaken. |
|  [targetSdkVersion?](./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.shakevisitorconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [ShakeVisitorConfig](./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](./react-rsbuild-plugin.shakevisitorconfig.pkgname.md) |  | Array&lt;string&gt; | Package names to identify runtime imports that need to be processed |
|  [removeCallParams](./react-rsbuild-plugin.shakevisitorconfig.removecallparams.md) |  | Array&lt;string&gt; | Function names whose parameters should be removed during transformation |
|  [retainProp](./react-rsbuild-plugin.shakevisitorconfig.retainprop.md) |  | Array&lt;string&gt; | Properties that should be retained in the component class |




---
url: /api/rspeedy/rspeedy.buildcache.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [BuildCache](./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?](./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?](./rspeedy.buildcache.cachedigest.md) |  | Array&lt;string \| undefined&gt; \| undefined | **_(BETA)_** _(Optional)_ Add additional cache digests, the previous build cache will be invalidated when any value in the array changes. |
|  [cacheDirectory?](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplit](./rspeedy.chunksplit.md)

## ChunkSplit interface

[Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplit 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [override?](./rspeedy.chunksplit.override.md) |  | Rspack.Configuration extends { optimization?: { splitChunks?: infer P; } \| undefined; } ? P : never | _(Optional)_ Custom Rspack chunk splitting config can be specified. |
|  [strategy?](./rspeedy.chunksplit.strategy.md) |  | 'all-in-one' \| 'split-by-module' \| 'split-by-experience' \| 'single-vendor' \| undefined | _(Optional)_ The ChunkSplitting strategy. |




---
url: /api/rspeedy/rspeedy.chunksplitbysize.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitBySize](./rspeedy.chunksplitbysize.md)

## ChunkSplitBySize interface

[Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplitBySize 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [maxSize?](./rspeedy.chunksplitbysize.maxsize.md) |  | number \| undefined | _(Optional)_ The maximum size of a chunk, unit in bytes. Defaults to <code>Number.POSITIVE_INFINITY</code>. |
|  [minSize?](./rspeedy.chunksplitbysize.minsize.md) |  | number \| undefined | _(Optional)_ The minimum size of a chunk, unit in bytes. Defaults to <code>10000</code>. |
|  [override?](./rspeedy.chunksplitbysize.override.md) |  | Rspack.Configuration extends { optimization?: { splitChunks?: infer P; } \| undefined; } ? P : never | _(Optional)_ Custom Rspack chunk splitting config can be specified. |
|  [strategy](./rspeedy.chunksplitbysize.strategy.md) |  | 'split-by-size' | The ChunkSplitting strategy. |




---
url: /api/rspeedy/rspeedy.chunksplitbysize.override.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitBySize](./rspeedy.chunksplitbysize.md) &gt; [override](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitBySize](./rspeedy.chunksplitbysize.md) &gt; [strategy](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitCustom](./rspeedy.chunksplitcustom.md)

## ChunkSplitCustom interface

[Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplitCustom 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [splitChunks?](./rspeedy.chunksplitcustom.splitchunks.md) |  | Rspack.Configuration extends { optimization?: { splitChunks?: infer P; } \| undefined; } ? P : never | _(Optional)_ Custom Rspack chunk splitting config can be specified. |
|  [strategy](./rspeedy.chunksplitcustom.strategy.md) |  | 'custom' | The ChunkSplitting strategy. |




---
url: /api/rspeedy/rspeedy.chunksplitcustom.strategy.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitCustom](./rspeedy.chunksplitcustom.md) &gt; [strategy](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [dev](./rspeedy.config.dev.md)

## Config.dev property

The [Dev](./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.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md)

## Config interface

The `Config` is the configuration that `rspeedy` uses.

**Signature:**

```typescript
export interface Config 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [dev?](./rspeedy.config.dev.md) |  | [Dev](./rspeedy.dev.md) \| undefined | _(Optional)_ The [Dev](./rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc. |
|  [environments?](./rspeedy.config.environments.md) |  | RsbuildConfig\['environments'\] \| undefined | _(Optional)_ The [Config.environments](./rspeedy.config.environments.md) option is used to set the output environment. |
|  [mode?](./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?](./rspeedy.config.output.md) |  | [Output](./rspeedy.output.md) \| undefined | _(Optional)_ The [Output](./rspeedy.output.md) option is used to set how and where should the bundles and assets output. |
|  [performance?](./rspeedy.config.performance.md) |  | [Performance](./rspeedy.performance.md) \| undefined | _(Optional)_ The [Performance](./rspeedy.performance.md) option is used to |
|  [plugins?](./rspeedy.config.plugins.md) |  | RsbuildPlugins \| undefined | _(Optional)_ The <code>plugins</code> option is used to customize the build process in a variety of ways. |
|  [provider?](./rspeedy.config.provider.md) |  | RsbuildConfig\['provider'\] | **_(ALPHA)_** _(Optional)_ The Rsbuild provider. |
|  [server?](./rspeedy.config.server.md) |  | [Server](./rspeedy.server.md) \| undefined | _(Optional)_ The [Server](./rspeedy.server.md) option changes the behavior of dev-server. |
|  [source?](./rspeedy.config.source.md) |  | [Source](./rspeedy.source.md) \| undefined | _(Optional)_ The [Source](./rspeedy.source.md) option changes the behavior of source files. |
|  [tools?](./rspeedy.config.tools.md) |  | [Tools](./rspeedy.tools.md) \| undefined | _(Optional)_ The [Tools](./rspeedy.tools.md) options changes the behavior of various building tools. |




---
url: /api/rspeedy/rspeedy.config.output.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [output](./rspeedy.config.output.md)

## Config.output property

The [Output](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [performance](./rspeedy.config.performance.md)

## Config.performance property

The [Performance](./rspeedy.performance.md) option is used to

**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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [plugins](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [provider](./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.server.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [server](./rspeedy.config.server.md)

## Config.server property

The [Server](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [source](./rspeedy.config.source.md)

## Config.source property

The [Source](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [tools](./rspeedy.config.tools.md)

## Config.tools property

The [Tools](./rspeedy.tools.md) options changes the behavior of various building tools.

**Signature:**

```typescript
tools?: Tools | undefined;
```



---
url: /api/rspeedy/rspeedy.consoletype.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ConsoleType](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [createRspeedy](./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](./rspeedy.createrspeedyoptions.md) |  |

**Returns:**

Promise&lt;[RspeedyInstance](./rspeedy.rspeedyinstance.md)<!-- -->&gt;

- 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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CreateRspeedyOptions](./rspeedy.createrspeedyoptions.md) &gt; [callerName](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CreateRspeedyOptions](./rspeedy.createrspeedyoptions.md) &gt; [cwd](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CreateRspeedyOptions](./rspeedy.createrspeedyoptions.md) &gt; [environment](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CreateRspeedyOptions](./rspeedy.createrspeedyoptions.md) &gt; [loadEnv](./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). 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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CreateRspeedyOptions](./rspeedy.createrspeedyoptions.md)

## CreateRspeedyOptions interface

The options of `createRspeedy` method.

**Signature:**

```typescript
export interface CreateRspeedyOptions 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [callerName?](./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?](./rspeedy.createrspeedyoptions.cwd.md) |  | string | _(Optional)_ The root path of the current build. |
|  [environment?](./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?](./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). 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?](./rspeedy.createrspeedyoptions.rspeedyconfig.md) |  | [Config](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CreateRspeedyOptions](./rspeedy.createrspeedyoptions.md) &gt; [rspeedyConfig](./rspeedy.createrspeedyoptions.rspeedyconfig.md)

## CreateRspeedyOptions.rspeedyConfig property

The config of Rspeedy.

**Signature:**

```typescript
rspeedyConfig?: Config;
```



---
url: /api/rspeedy/rspeedy.cssextract.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtract](./rspeedy.cssextract.md)

## CssExtract interface

The [CssExtract](./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?](./rspeedy.cssextract.loaderoptions.md) |  | [CssExtractRspackLoaderOptions](./rspeedy.cssextractrspackloaderoptions.md) \| undefined | _(Optional)_ The options of CSS extract loader. |
|  [pluginOptions?](./rspeedy.cssextract.pluginoptions.md) |  | [CssExtractRspackPluginOptions](./rspeedy.cssextractrspackpluginoptions.md) \| undefined | _(Optional)_ The options for [CssExtractRspackPlugin](https://rspack.dev/plugins/rspack/css-extract-rspack-plugin) |




---
url: /api/rspeedy/rspeedy.cssextractrspackloaderoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtractRspackLoaderOptions](./rspeedy.cssextractrspackloaderoptions.md)

## CssExtractRspackLoaderOptions interface

The options of CSS extract loader.

**Signature:**

```typescript
export interface CssExtractRspackLoaderOptions 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [esModule?](./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.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtractRspackPluginOptions](./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?](./rspeedy.cssextractrspackpluginoptions.ignoreorder.md) |  | boolean \| undefined | _(Optional)_ |
|  [pathinfo?](./rspeedy.cssextractrspackpluginoptions.pathinfo.md) |  | boolean \| undefined | _(Optional)_ |




---
url: /api/rspeedy/rspeedy.cssloader.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoader](./rspeedy.cssloader.md)

## CssLoader interface

The [CssLoader](./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?](./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?](./rspeedy.cssloader.modules.md) |  | boolean \| [CssLoaderModules](./rspeedy.cssloadermodules.md) \| undefined | _(Optional)_ The [cssLoader.modules](./rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior. |




---
url: /api/rspeedy/rspeedy.cssloadermodules.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoaderModules](./rspeedy.cssloadermodules.md)

## CssLoaderModules interface

The [cssLoader.modules](./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?](./rspeedy.cssloadermodules.auto.md) |  | boolean \| RegExp \| ((filename: string) =&gt; boolean) \| undefined | _(Optional)_ The <code>auto</code> option allows CSS modules to be automatically enabled based on their filenames. |
|  [exportLocalsConvention?](./rspeedy.cssloadermodules.exportlocalsconvention.md) |  | [CssModuleLocalsConvention](./rspeedy.cssmodulelocalsconvention.md) \| undefined | _(Optional)_ The style of exported class names. |
|  [localIdentName?](./rspeedy.cssloadermodules.localidentname.md) |  | string \| undefined | _(Optional)_ Sets the format of the className generated by CSS Modules after compilation. |
|  [namedExport?](./rspeedy.cssloadermodules.namedexport.md) |  | boolean \| undefined | _(Optional)_ Enables/disables ES modules named export for locals. |




---
url: /api/rspeedy/rspeedy.cssmodulelocalsconvention.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssModuleLocalsConvention](./rspeedy.cssmodulelocalsconvention.md)

## CssModuleLocalsConvention type

The style of exported class names.

**Signature:**

```typescript
export type CssModuleLocalsConvention = 'asIs' | 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly';
```

## Remarks

Given the various `exportLocalsConvention` values, the behavior is described as follows:

- `'asIs'`<!-- -->: Class names will be exported as is.

- `'camelCase'`<!-- -->: Class names will be camelized, the original class name will not to be removed from the locals

- `'camelCaseOnly'`<!-- -->: Class names will be camelized, the original class name will be removed from the locals

- `'dashes'`<!-- -->: Only dashes in class names will be camelized

- `'dashesOnly'`<!-- -->: Dashes in class names will be camelized, the original class name will be removed from the locals

See [css-loader\#exportLocalsConvention](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention) for details.




---
url: /api/rspeedy/rspeedy.cssmodules.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssModules](./rspeedy.cssmodules.md)

## CssModules interface

The [CssModules](./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](./rspeedy.cssmodules.auto.md) to customize the filtering behavior.

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [auto?](./rspeedy.cssmodules.auto.md) |  | boolean \| RegExp \| ((filename: string) =&gt; boolean) \| undefined | _(Optional)_ The <code>auto</code> option allows CSS modules to be automatically enabled based on their filenames. |
|  [exportGlobals?](./rspeedy.cssmodules.exportglobals.md) |  | boolean \| undefined | _(Optional)_ Allows exporting names from global class names, so you can use them via import. |
|  [exportLocalsConvention?](./rspeedy.cssmodules.exportlocalsconvention.md) |  | [CssModuleLocalsConvention](./rspeedy.cssmodulelocalsconvention.md) \| undefined | _(Optional)_ The style of exported class names. |
|  [localIdentName?](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Decorators](./rspeedy.decorators.md)

## Decorators interface

Used to configure the decorators syntax.

**Signature:**

```typescript
export interface Decorators 
```

## Remarks

See [Decorators.version](./rspeedy.decorators.version.md) for more information.

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [version?](./rspeedy.decorators.version.md) |  | 'legacy' \| '2022-03' | _(Optional)_ Specify the decorator syntax version to be used. |




---
url: /api/rspeedy/rspeedy.defineconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [defineConfig](./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](./rspeedy.config.md) | The config of Rspeedy. |

**Returns:**

[Config](./rspeedy.config.md)

- The identical config as the input config.

## Example

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
//@ts-check
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  // autocompletion works here!
})
```




---
url: /api/rspeedy/rspeedy.devclient.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DevClient](./rspeedy.devclient.md)

## DevClient interface

Configuration of the development client.

**Signature:**

```typescript
export interface Client 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [websocketTransport?](./rspeedy.devclient.websockettransport.md) |  | string \| undefined | _(Optional)_ The path to websocket. |




---
url: /api/rspeedy/rspeedy.distpath.css.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DistPath](./rspeedy.distpath.md) &gt; [css](./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](./rspeedy.distpath.intermediate.md)




---
url: /api/rspeedy/rspeedy.distpath.cssasync.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DistPath](./rspeedy.distpath.md) &gt; [cssAsync](./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](./rspeedy.distpath.css.md)<!-- -->.




---
url: /api/rspeedy/rspeedy.distpath.js.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DistPath](./rspeedy.distpath.md) &gt; [js](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DistPath](./rspeedy.distpath.md) &gt; [jsAsync](./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](./rspeedy.distpath.js.md)<!-- -->.




---
url: /api/rspeedy/rspeedy.distpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DistPath](./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?](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DistPath](./rspeedy.distpath.md) &gt; [root](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Entry](./rspeedy.entry.md)

## Entry type

The [Entry](./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](./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](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [EntryDescription](./rspeedy.entrydescription.md) &gt; [import](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [EntryDescription](./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?](./rspeedy.entrydescription.import.md) |  | string \| string\[\] \| undefined | _(Optional)_ The path to the entry module(s). |
|  [publicPath?](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [EntryDescription](./rspeedy.entrydescription.md) &gt; [publicPath](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ExposedAPI](./rspeedy.exposedapi.md) &gt; [config](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ExposedAPI](./rspeedy.exposedapi.md) &gt; [debug](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ExposedAPI](./rspeedy.exposedapi.md) &gt; [exit](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ExposedAPI](./rspeedy.exposedapi.md) &gt; [logger](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ExposedAPI](./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](./rspeedy.exposedapi.config.md) |  | [Config](./rspeedy.config.md) | The user config. |
|  [debug](./rspeedy.exposedapi.debug.md) |  | (message: string \| (() =&gt; string)) =&gt; void | Print debug logs. |
|  [exit](./rspeedy.exposedapi.exit.md) |  | (code?: number) =&gt; Promise&lt;void&gt; \| void | Exit the process. |
|  [logger](./rspeedy.exposedapi.logger.md) |  | typeof logger | Get the Rspeedy logger. |
|  [version](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ExposedAPI](./rspeedy.exposedapi.md) &gt; [version](./rspeedy.exposedapi.version.md)

## ExposedAPI.version property

The version of Rspeedy.

**Signature:**

```typescript
version: string;
```



---
url: /api/rspeedy/rspeedy.filename.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md)

## Filename interface

The [Filename](./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](./rspeedy.filename.bundle.md)<!-- -->.

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [bundle?](./rspeedy.filename.bundle.md) |  | string \| undefined | _(Optional)_ The name of the bundle files. |
|  [css?](./rspeedy.filename.css.md) |  | string \| undefined | _(Optional)_ The name of the CSS files. |
|  [font?](./rspeedy.filename.font.md) |  | string \| undefined | _(Optional)_ The name of the font files. |
|  [image?](./rspeedy.filename.image.md) |  | string \| undefined | _(Optional)_ The name of non-SVG images. |
|  [js?](./rspeedy.filename.js.md) |  | string \| undefined | _(Optional)_ The name of the JavaScript files. |
|  [media?](./rspeedy.filename.media.md) |  | string \| undefined | _(Optional)_ The name of media assets, such as video. |
|  [svg?](./rspeedy.filename.svg.md) |  | string \| undefined | _(Optional)_ The name of the SVG images. |
|  [template?](./rspeedy.filename.template.md) |  | string \| undefined | _(Optional)_ The name of the template files. |




---
url: /api/rspeedy/rspeedy.loadconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [loadConfig](./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](./rspeedy.loadconfigoptions.md) | the options of <code>loadConfig</code> method. |

**Returns:**

Promise&lt;[LoadConfigResult](./rspeedy.loadconfigresult.md)<!-- -->&gt;

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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [LoadConfigOptions](./rspeedy.loadconfigoptions.md) &gt; [configPath](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [LoadConfigOptions](./rspeedy.loadconfigoptions.md) &gt; [cwd](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [LoadConfigOptions](./rspeedy.loadconfigoptions.md)

## LoadConfigOptions interface

The options of loadConfig.

**Signature:**

```typescript
export interface LoadConfigOptions 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [configPath?](./rspeedy.loadconfigoptions.configpath.md) |  | string \| undefined | _(Optional)_ |
|  [cwd?](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [LoadConfigResult](./rspeedy.loadconfigresult.md) &gt; [configPath](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [LoadConfigResult](./rspeedy.loadconfigresult.md) &gt; [content](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [LoadConfigResult](./rspeedy.loadconfigresult.md)

## LoadConfigResult interface

The result of [loadConfig()](./rspeedy.loadconfig.md)<!-- -->.

**Signature:**

```typescript
export interface LoadConfigResult 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [configPath](./rspeedy.loadconfigresult.configpath.md) |  | string | The configuration path that has been loaded. |
|  [content](./rspeedy.loadconfigresult.content.md) |  | [Config](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md)

## rspeedy package

The document contains all the configurations of the `@lynx-js/rspeedy` package.

## Example

Use `lynx.config.ts` with [defineConfig()](./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, })](./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)](./rspeedy.defineconfig.md) | The <code>defineConfig</code> method is a helper function used to get TypeScript intellisense. |
|  [loadConfig(loadConfigOptions)](./rspeedy.loadconfig.md) | Load the build config by the config path. |
|  [mergeRspeedyConfig(configs)](./rspeedy.mergerspeedyconfig.md) | Merge multiple Rspeedy configuration objects. |

## Interfaces

|  Interface | Description |
|  --- | --- |
|  [BuildCache](./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](./rspeedy.chunksplit.md) | [Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy. |
|  [ChunkSplitBySize](./rspeedy.chunksplitbysize.md) | [Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy. |
|  [ChunkSplitCustom](./rspeedy.chunksplitcustom.md) | [Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy. |
|  [Config](./rspeedy.config.md) | The <code>Config</code> is the configuration that <code>rspeedy</code> uses. |
|  [CreateRspeedyOptions](./rspeedy.createrspeedyoptions.md) | The options of <code>createRspeedy</code> method. |
|  [CssExtract](./rspeedy.cssextract.md) | The [CssExtract](./rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin) |
|  [CssExtractRspackLoaderOptions](./rspeedy.cssextractrspackloaderoptions.md) | The options of CSS extract loader. |
|  [CssExtractRspackPluginOptions](./rspeedy.cssextractrspackpluginoptions.md) | The options for [CssExtractRspackPlugin](https://rspack.dev/plugins/rspack/css-extract-rspack-plugin) |
|  [CssLoader](./rspeedy.cssloader.md) | The [CssLoader](./rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->. |
|  [CssLoaderModules](./rspeedy.cssloadermodules.md) | The [cssLoader.modules](./rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior. |
|  [CssModules](./rspeedy.cssmodules.md) | The [CssModules](./rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations. |
|  [Decorators](./rspeedy.decorators.md) | Used to configure the decorators syntax. |
|  [Dev](./rspeedy.dev.md) | The [Dev](./rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc. |
|  [DevClient](./rspeedy.devclient.md) | Configuration of the development client. |
|  [DistPath](./rspeedy.distpath.md) | Set the directory of the dist files. |
|  [EntryDescription](./rspeedy.entrydescription.md) | The <code>EntryDescription</code> describes a entry. It is useful when the project has multiple entries with different configuration. |
|  [ExposedAPI](./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](./rspeedy.filename.md) | The [Filename](./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](./rspeedy.loadconfigoptions.md) | The options of loadConfig. |
|  [LoadConfigResult](./rspeedy.loadconfigresult.md) | The result of [loadConfig()](./rspeedy.loadconfig.md)<!-- -->. |
|  [Minify](./rspeedy.minify.md) | The [Minify](./rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options. |
|  [Output](./rspeedy.output.md) | The [Output](./rspeedy.output.md) option is used to set how and where should the bundles and assets output. |
|  [Performance](./rspeedy.performance.md) | The [Performance](./rspeedy.performance.md) option is used to |
|  [Server](./rspeedy.server.md) | The [Server](./rspeedy.server.md) option changes the behavior of dev-server. |
|  [Source](./rspeedy.source.md) | The [Source](./rspeedy.source.md) option changes the behavior of source files. |
|  [SourceMap](./rspeedy.sourcemap.md) | The [SourceMap](./rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs. |
|  [Tools](./rspeedy.tools.md) | The [Tools](./rspeedy.tools.md) options changes the behavior of various building tools. |
|  [TransformImport](./rspeedy.transformimport.md) | The [TransformImport](./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](./rspeedy.rspackversion.md) |  |
|  [version](./rspeedy.version.md) |  |

## Type Aliases

|  Type Alias | Description |
|  --- | --- |
|  [ConsoleType](./rspeedy.consoletype.md) | The type of the console method. |
|  [CssModuleLocalsConvention](./rspeedy.cssmodulelocalsconvention.md) | The style of exported class names. |
|  [Entry](./rspeedy.entry.md) | The [Entry](./rspeedy.entry.md) option is used to set the entry module. |
|  [RsdoctorRspackPluginOptions](./rspeedy.rsdoctorrspackpluginoptions.md) |  |
|  [RspeedyInstance](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [mergeRspeedyConfig](./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](./rspeedy.config.md)<!-- -->\[\] | The Rspeedy configuration objects to merge. |

**Returns:**

[Config](./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.cssoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Minify](./rspeedy.minify.md) &gt; [cssOptions](./rspeedy.minify.cssoptions.md)

## Minify.cssOptions property

[Minify.cssOptions](./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.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Minify](./rspeedy.minify.md)

## Minify interface

The [Minify](./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?](./rspeedy.minify.css.md) |  | boolean \| undefined | _(Optional)_ Whether enable the CSS minification. |
|  [js?](./rspeedy.minify.js.md) |  | boolean \| undefined | _(Optional)_ Whether enable the JavaScript minification. |
|  [jsOptions?](./rspeedy.minify.jsoptions.md) |  | Rspack.SwcJsMinimizerRspackPluginOptions \| undefined | _(Optional)_ [Minify.jsOptions](./rspeedy.minify.jsoptions.md) is used to configure SWC minification options. |




---
url: /api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [RsdoctorRspackPluginOptions](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [rspackVersion](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [RspeedyInstance](./rspeedy.rspeedyinstance.md)

## RspeedyInstance type

The instance of Rspeedy.

**Signature:**

```typescript
export type RspeedyInstance = RsbuildInstance & {
    getRspeedyConfig(): Config;
};
```
**References:** [Config](./rspeedy.config.md)




---
url: /api/rspeedy/rspeedy.sourcemap.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [SourceMap](./rspeedy.sourcemap.md)

## SourceMap interface

The [SourceMap](./rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

**Signature:**

```typescript
export interface SourceMap 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [js?](./rspeedy.sourcemap.js.md) |  | Rspack.DevTool \| undefined \| \`${Exclude&lt;Rspack.DevTool, false \| 'eval'&gt;}-debugids\` | _(Optional)_ How the source map should be generated. Setting it to <code>false</code> will disable the source map. |




---
url: /api/rspeedy/rspeedy.transformimport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [TransformImport](./rspeedy.transformimport.md)

## TransformImport interface

The [TransformImport](./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?](./rspeedy.transformimport.cameltodashcomponentname.md) |  | boolean \| undefined | _(Optional)_ Whether to convert camelCase imports to kebab-case. |
|  [customName?](./rspeedy.transformimport.customname.md) |  | string \| undefined | _(Optional)_ Customize the transformed path. |
|  [libraryDirectory?](./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](./rspeedy.transformimport.libraryname.md) |  | string | The original import path that needs to be transformed. |
|  [transformToDefaultImport?](./rspeedy.transformimport.transformtodefaultimport.md) |  | boolean \| undefined | _(Optional)_ Whether to convert import statements to default imports. |




---
url: /api/rspeedy/rspeedy.version.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [version](./rspeedy.version.md)

## version variable

**Signature:**

```typescript
version: string
```



---
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](/en/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) |
| [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 |
| ------ | ------ |
| [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) | - |
| [createRoot](/api/react/Function.createRoot.md) | The default and only root of ReactLynx for you to render JSX |
| [forwardRef](/api/react/Function.forwardRef.md) | Lets your component expose an element 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 js context 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. |
| [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 |

## Directives

| Document | Description |
| ------ | ------ |
| [directives](/api/react/Document.directives.md) | - |

## Globals

| Document | Description |
| ------ | ------ |
| [built-in-macros](/api/react/Document.built-in-macros.md) | - |



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



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



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



[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 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>): null | SS
```

Runs before React applies the result of [render](/api/react/Class.Component.md#render) to the document, and
returns an object to be given to [componentDidUpdate](/api/react/Class.Component.md#componentdidupdate). Useful for saving
things such as scroll position before [render](/api/react/Class.Component.md#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated
lifecycle events from running.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |

#### Returns

`null` | `SS`

#### Inherited from

`ComponentLifecycle.getSnapshotBeforeUpdate`

#### Defined in

.pnpm/@types+react@18.3.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: null | S | (prevState: Readonly<S>, props: Readonly<P>) => null | S | Pick<S, K> | Pick<S, K>, callback?: () => void): void
```

#### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* `string` | `number` | `symbol` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `state` | `null` | `S` | (`prevState`: `Readonly`\<`S`>, `props`: `Readonly`\<`P`>) => `null` | `S` | `Pick`\<`S`, `K`> | `Pick`\<`S`, `K`> |
| `callback`? | () => `void` |

#### Returns

`void`

#### Defined in

.pnpm/@types+react@18.3.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. */}



[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/workletRef.d.ts:14

## 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/workletRef.d.ts:3



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



[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 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>): null | SS
```

Runs before React applies the result of [render](/api/react/Class.Component.md#render) to the document, and
returns an object to be given to [componentDidUpdate](/api/react/Class.PureComponent.md#componentdidupdate). Useful for saving
things such as scroll position before [render](/api/react/Class.Component.md#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated
lifecycle events from running.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |

#### Returns

`null` | `SS`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`getSnapshotBeforeUpdate`](/api/react/Class.Component.md#getsnapshotbeforeupdate)

#### Defined in

.pnpm/@types+react@18.3.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: null | S | (prevState: Readonly<S>, props: Readonly<P>) => null | S | Pick<S, K> | Pick<S, K>, callback?: () => void): void
```

#### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* `string` | `number` | `symbol` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `state` | `null` | `S` | (`prevState`: `Readonly`\<`S`>, `props`: `Readonly`\<`P`>) => `null` | `S` | `Pick`\<`S`, `K`> | `Pick`\<`S`, `K`> |
| `callback`? | () => `void` |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`setState`](/api/react/Class.Component.md#setstate)

#### Defined in

.pnpm/@types+react@18.3.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/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. */}



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



[react](/api/react/index.md) / createElement

# Function: createElement()

## createElement(type, props, children)

```ts
function createElement(
   type: "input",
   props?: null | InputHTMLAttributes<HTMLInputElement> & ClassAttributes<HTMLInputElement>, ...
children?: ReactNode[]): DetailedReactHTMLElement<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>
```

### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `"input"` |
| `props`? | `null` | `InputHTMLAttributes`\<`HTMLInputElement`> & `ClassAttributes`\<`HTMLInputElement`> |
| ...`children`? | `ReactNode`\[] |

### Returns

`DetailedReactHTMLElement`\<`InputHTMLAttributes`\<`HTMLInputElement`>, `HTMLInputElement`>

### Defined in

.pnpm/@types+react@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:522

## createElement(type, props, children)

```ts
function createElement<P, T>(
   type: keyof ReactHTML,
   props?: null | ClassAttributes<T> & P, ...
children?: ReactNode[]): DetailedReactHTMLElement<P, T>
```

### Type Parameters

| Type Parameter |
| ------ |
| `P` *extends* `HTMLAttributes`\<`T`, `P`> |
| `T` *extends* `HTMLElement` |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | keyof `ReactHTML` |
| `props`? | `null` | `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?: null | ClassAttributes<T> & P, ...
   children?: ReactNode[]): ReactSVGElement
```

### Type Parameters

| Type Parameter |
| ------ |
| `P` *extends* `SVGAttributes`\<`T`, `P`> |
| `T` *extends* `SVGElement` |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | keyof `ReactSVG` |
| `props`? | `null` | `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?: null | ClassAttributes<T> & P, ...
children?: ReactNode[]): DOMElement<P, T>
```

### Type Parameters

| Type Parameter |
| ------ |
| `P` *extends* `DOMAttributes`\<`T`, `P`> |
| `T` *extends* `Element` |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `string` |
| `props`? | `null` | `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?: null | Attributes & P, ...
children?: ReactNode[]): FunctionComponentElement<P>
```

### Type Parameters

| Type Parameter |
| ------ |
| `P` *extends* `object` |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `FunctionComponent`\<`P`> |
| `props`? | `null` | `Attributes` & `P` |
| ...`children`? | `ReactNode`\[] |

### Returns

`FunctionComponentElement`\<`P`>

### Defined in

.pnpm/@types+react@18.3.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?: null | ClassAttributes<T> & P, ...
children?: ReactNode[]): CElement<P, T>
```

### Type Parameters

| Type Parameter |
| ------ |
| `P` *extends* `object` |
| `T` *extends* [`Component`](/api/react/Class.Component.md)\<`P`, `any`, `any`, `T`> |
| `C` *extends* `ComponentClass`\<`P`, `any`, `C`> |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `ClassType`\<`P`, `T`, `C`> |
| `props`? | `null` | `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[] |

### Returns

`CElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react@18.3.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?: null | Attributes & P, ...
children?: ReactNode[]): ReactElement<P>
```

### Type Parameters

| Type Parameter |
| ------ |
| `P` *extends* `object` |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `string` | `FunctionComponent`\<`P`> | `ComponentClass`\<`P`, `any`> |
| `props`? | `null` | `Attributes` & `P` |
| ...`children`? | `ReactNode`\[] |

### Returns

`ReactElement`\<`P`>

### Defined in

.pnpm/@types+react@18.3.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. */}



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



[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 an element node to a parent component
using a ref.

## Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
| `T` | - | The type of the element 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.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. */}



[react](/api/react/index.md) / Fragment

# Function: Fragment()

```ts
function Fragment(props: object): null | ReactElement<any, string | JSXElementConstructor<any>>
```

Lets you group elements without a wrapper node.

## Parameters

| Parameter | Type |
| ------ | ------ |
| `props` | `object` |
| `props.children`? | `ReactNode` |

## Returns

`null` | `ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## See

[React Docs](https://react.dev/reference/react/Fragment)

## Examples

```tsx
import { Fragment } from 'react';

<Fragment>
  <td>Hello</td>
  <td>World</td>
</Fragment>
```

```tsx
// Using the <></> shorthand syntax:

<>
  <td>Hello</td>
  <td>World</td>
</>
```

## Defined in

.pnpm/@types+react@18.3.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. */}



[react](/api/react/index.md) / InitDataConsumer

# Function: InitDataConsumer()

```ts
function InitDataConsumer(props: ConsumerProps<InitData>): null | ReactElement<any, string | JSXElementConstructor<any>>
```

The [Consumer](https://react.dev/reference/react/createContext#consumer) Component that provide `initData`.
This should be used with [InitDataProvider](/api/react/Function.InitDataProvider.md)

## Parameters

| Parameter | Type |
| ------ | ------ |
| `props` | `ConsumerProps`\<[`InitData`](/api/react/Interface.InitData.md)> |

## Returns

`null` | `ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:115



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



[react](/api/react/index.md) / InitDataProvider

# Function: InitDataProvider()

```ts
function InitDataProvider(props: object, deprecatedLegacyContext?: any): null | ReactElement<any, any>
```

The [Provider](https://react.dev/reference/react/createContext#provider) Component that provide `initData`,
you must wrap your JSX inside it

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `props` | `object` | - |
| `props.children`? | `ReactNode` | - |
| `deprecatedLegacyContext`? | `any` | **Deprecated** **See** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |

## Returns

`null` | `ReactElement`\<`any`, `any`>

## Example

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

function App() {
  return (
    <InitDataConsumer children={(initData) => <view>...</view>}/>
  )
}

root.render(
  <InitDataProvider>
     <App/>
  </InitDataProvider>
);

```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:106



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



[react](/api/react/index.md) / isValidElement

# Function: isValidElement()

```ts
function isValidElement<P>(object: undefined | null | object): object is ReactElement<P, string | JSXElementConstructor<any>>
```

## Type Parameters

| Type Parameter |
| ------ |
| `P` |

## Parameters

| Parameter | Type |
| ------ | ------ |
| `object` | `undefined` | `null` | `object` |

## Returns

object is ReactElement\<P, string | JSXElementConstructor\<any>>

## Defined in

.pnpm/@types+react@18.3.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. */}



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



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



[react](/api/react/index.md) / runOnBackground

# Function: runOnBackground()

```ts
function runOnBackground<Fn>(f: Fn): (...args: Parameters<Fn>) => void
```

`runOnBackground` allows triggering js functions on the js context asynchronously.

## Type Parameters

| Type Parameter |
| ------ |
| `Fn` *extends* (...`args`: `any`\[]) => `any` |

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

### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`args` | `Parameters`\<`Fn`> |

### Returns

`void`

## Defined in

@lynx-js/react/runtime/lib/worklet/runWorklet.d.ts:14



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



[react](/api/react/index.md) / runOnMainThread

# Function: runOnMainThread()

```ts
function runOnMainThread<Fn>(fn: Fn): (...args: Parameters<Fn>) => void
```

`runOnMainThread` allows triggering main thread functions on the main thread asynchronously.

## Type Parameters

| Type Parameter |
| ------ |
| `Fn` *extends* (...`args`: `any`\[]) => `any` |

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

### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`args` | `Parameters`\<`Fn`> |

### Returns

`void`

## Defined in

@lynx-js/react/runtime/lib/worklet/runWorklet.d.ts:7



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



[react](/api/react/index.md) / Suspense

# Function: Suspense()

```ts
function Suspense(props: SuspenseProps): null | ReactElement<any, string | JSXElementConstructor<any>>
```

Lets you display a fallback until its children have finished loading.

## Parameters

| Parameter | Type |
| ------ | ------ |
| `props` | `SuspenseProps` |

## Returns

`null` | `ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## See

[React Docs](https://react.dev/reference/react/Suspense)

## Example

```tsx
import { Suspense } from 'react';

<Suspense fallback={<Loading />}>
  <ProfileDetails />
</Suspense>
```

## Defined in

.pnpm/@types+react@18.3.11/node\_modules/@types/react/ts5.0/index.d.ts:875



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



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



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



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



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



[react](/api/react/index.md) / useImperativeHandle

# Function: useImperativeHandle()

```ts
function useImperativeHandle<T, R>(
   ref: undefined | Ref<T>,
   init: () => R,
   deps?: DependencyList): void
```

`useImperativeHandle` customizes the instance value that is exposed to parent components when using
`ref`. As always, imperative code using refs should be avoided in most cases.

`useImperativeHandle` should be used with `React.forwardRef`.

## Type Parameters

| Type Parameter |
| ------ |
| `T` |
| `R` |

## Parameters

| Parameter | Type |
| ------ | ------ |
| `ref` | `undefined` | `Ref`\<`T`> |
| `init` | () => `R` |
| `deps`? | `DependencyList` |

## Returns

`void`

## Version

16.8.0

## See

[https://react.dev/reference/react/useImperativeHandle](https://react.dev/reference/react/useImperativeHandle)

## Defined in

.pnpm/@types+react@18.3.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. */}



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



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



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



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



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



[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`: `unknown`\[]) => `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. */}



[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/workletRef.d.ts:54

## useMainThreadRef(initValue)

```ts
function useMainThreadRef<T>(initValue: null | T): RefObject<T>
```

Create A `MainThreadRef`.

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

It is a hook and it should only be called at the top level of your component.

### Type Parameters

| Type Parameter |
| ------ |
| `T` |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `initValue` | `null` | `T` | The init value of the `MainThreadRef`. |

### Returns

`RefObject`\<`T`>

### Example

```ts
import { useMainThreadRef } from '@lynx-js/react'
import type { MainThread } from '@lynx-js/types'

export function App() {
  const ref = useMainThreadRef<MainThread.Element>(null)

  const handleTap = () => {
    'main thread'
    ref.current?.setStyleProperty('background-color', 'blue')
  }

  return (
    <view
      main-thread:ref={ref}
      main-thread:bindtap={handleTap}
      style={{ width: '300px', height: '300px' }}
    />
  )
}
```

### Defined in

@lynx-js/react/runtime/lib/worklet/workletRef.d.ts:93

## 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/workletRef.d.ts:130



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



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



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



[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: null | T): RefObject<T>
```

`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
(`initialValue`). The returned object will persist for the full lifetime of the component.

Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.

Usage note: if you need the result of useRef to be directly mutable, include `| null` in the type
of the generic argument.

### Type Parameters

| Type Parameter |
| ------ |
| `T` |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `initialValue` | `null` | `T` |

### Returns

`RefObject`\<`T`>

### Version

16.8.0

### See

[https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### Defined in

.pnpm/@types+react@18.3.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. */}



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



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



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



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



[react](/api/react/index.md) / DataProcessorDefinition

# Interface: DataProcessorDefinition

Definition of DataProcessor(s)

## Properties

### dataProcessors?

```ts
optional dataProcessors: Record<string, Function>;
```

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

***

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



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



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



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



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

***

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



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



[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 (__LEPUS__) {
  root.render(
    <DataProvider data={DEFAULT_DATA}>
       <App/>
    </DataProvider>
  );
} else if (__JS__) {
  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. */}



[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/rspeedy/index.md
---




---
url: /api/rspeedy/rspeedy.config.environments.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [environments](./rspeedy.config.environments.md)

## Config.environments property

The [Config.environments](./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.mode.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Config](./rspeedy.config.md) &gt; [mode](./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](./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](./rspeedy.output.filenamehash.md)<!-- -->.

- Generated CSS Modules classnames will be shorter, see [CssModules.localIdentName](./rspeedy.cssmodules.localidentname.md)<!-- -->.

- Do not generate JavaScript and CSS source maps, see [Output.sourceMap](./rspeedy.output.sourcemap.md)<!-- -->.

- The `process.env.NODE_ENV` in the source code will be replaced with `'production'`<!-- -->.

- The `import.meta.env.MODE` in the source code will be replaced with `'production'`<!-- -->.

- The `import.meta.env.DEV` in the source code will be replaced with `false`<!-- -->.

- The `import.meta.env.PROD` in the source code will be replaced with `true`<!-- -->.




---
url: /api/rspeedy/rspeedy.dev.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md)

## Dev interface

The [Dev](./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?](./rspeedy.dev.assetprefix.md) |  | string \| boolean \| undefined | _(Optional)_ The [Dev.assetPrefix](./rspeedy.dev.assetprefix.md) is used to set the URL prefix for static assets during development. |
|  [client?](./rspeedy.dev.client.md) |  | [Client](./rspeedy.devclient.md) \| undefined | _(Optional)_ Configuration of the development client. |
|  [hmr?](./rspeedy.dev.hmr.md) |  | boolean \| undefined | _(Optional)_ Whether to enable Hot Module Replacement (HMR). |
|  [liveReload?](./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](./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?](./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?](./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?](./rspeedy.dev.writetodisk.md) |  | boolean \| ((filename: string) =&gt; boolean) \| undefined | _(Optional)_ Used to control whether the build artifacts of the development environment are written to the disk. |




---
url: /api/rspeedy/rspeedy.dev.assetprefix.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md) &gt; [assetPrefix](./rspeedy.dev.assetprefix.md)

## Dev.assetPrefix property

The [Dev.assetPrefix](./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](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md) &gt; [client](./rspeedy.dev.client.md)

## Dev.client property

Configuration of the development client.

**Signature:**

```typescript
client?: Client | undefined;
```



---
url: /api/rspeedy/rspeedy.devclient.websockettransport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DevClient](./rspeedy.devclient.md) &gt; [websocketTransport](./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.dev.hmr.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md) &gt; [hmr](./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](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md) &gt; [liveReload](./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](./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.progressbar.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md) &gt; [progressBar](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md) &gt; [watchFiles](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Dev](./rspeedy.dev.md) &gt; [writeToDisk](./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.output.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md)

## Output interface

The [Output](./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?](./rspeedy.output.assetprefix.md) |  | string \| undefined | _(Optional)_ The [Output.assetPrefix](./rspeedy.output.assetprefix.md) is used to set the URL prefix for static assets. |
|  [cleanDistPath?](./rspeedy.output.cleandistpath.md) |  | boolean \| undefined | _(Optional)_ The [Output.cleanDistPath](./rspeedy.output.cleandistpath.md) option determines whether all files in the output directory (default: <code>dist</code>) are removed before the build starts. |
|  [copy?](./rspeedy.output.copy.md) |  | Rspack.CopyRspackPluginOptions \| Rspack.CopyRspackPluginOptions\['patterns'\] \| undefined | _(Optional)_ The [Output.copy](./rspeedy.output.copy.md) option is used for copying files to the dist directory. |
|  [cssModules?](./rspeedy.output.cssmodules.md) |  | [CssModules](./rspeedy.cssmodules.md) \| undefined | _(Optional)_ The [CssModules](./rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations. |
|  [dataUriLimit?](./rspeedy.output.dataurilimit.md) |  | number \| undefined | _(Optional)_ The [Output.dataUriLimit](./rspeedy.output.dataurilimit.md) option is used to set the size threshold to inline static assets such as images and fonts. |
|  [distPath?](./rspeedy.output.distpath.md) |  | [DistPath](./rspeedy.distpath.md) \| undefined | _(Optional)_ Set the directory of the dist files. |
|  [filename?](./rspeedy.output.filename.md) |  | string \| [Filename](./rspeedy.filename.md) \| undefined | _(Optional)_ The [Filename](./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?](./rspeedy.output.filenamehash.md) |  | boolean \| string \| undefined | _(Optional)_ The [Output.filenameHash](./rspeedy.output.filenamehash.md) option controls whether to add a hash value to the filename after the production build. |
|  [inlineScripts?](./rspeedy.output.inlinescripts.md) |  | InlineChunkConfig \| undefined | _(Optional)_ The [Output.inlineScripts](./rspeedy.output.inlinescripts.md) option controls whether to inline scripts into Lynx bundle (<code>.lynx.bundle</code>). |
|  [legalComments?](./rspeedy.output.legalcomments.md) |  | 'none' \| 'inline' \| 'linked' \| undefined | _(Optional)_ The [Output.legalComments](./rspeedy.output.legalcomments.md) controls how to handle the legal comment. |
|  [minify?](./rspeedy.output.minify.md) |  | [Minify](./rspeedy.minify.md) \| boolean \| undefined | _(Optional)_ The [Minify](./rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options. |
|  [sourceMap?](./rspeedy.output.sourcemap.md) |  | boolean \| [SourceMap](./rspeedy.sourcemap.md) \| undefined | _(Optional)_ The [SourceMap](./rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs. |




---
url: /api/rspeedy/rspeedy.output.assetprefix.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [assetPrefix](./rspeedy.output.assetprefix.md)

## Output.assetPrefix property

The [Output.assetPrefix](./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](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [cleanDistPath](./rspeedy.output.cleandistpath.md)

## Output.cleanDistPath property

The [Output.cleanDistPath](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [copy](./rspeedy.output.copy.md)

## Output.copy property

The [Output.copy](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [cssModules](./rspeedy.output.cssmodules.md)

## Output.cssModules property

The [CssModules](./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](./rspeedy.cssmodules.auto.md) to customize the filtering behavior.

## Example 1

Disable CSS modules:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: false,
    },
  },
})
```

## Example 2

Enable CSS modules for all CSS files:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: () => true,
    },
  },
})
```




---
url: /api/rspeedy/rspeedy.cssmodules.auto.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssModules](./rspeedy.cssmodules.md) &gt; [auto](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssModules](./rspeedy.cssmodules.md) &gt; [exportGlobals](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssModules](./rspeedy.cssmodules.md) &gt; [exportLocalsConvention](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssModules](./rspeedy.cssmodules.md) &gt; [localIdentName](./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

See [css-loader\#localIdentName](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#localIdentName) for details.




---
url: /api/rspeedy/rspeedy.output.dataurilimit.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [dataUriLimit](./rspeedy.output.dataurilimit.md)

## Output.dataUriLimit property

The [Output.dataUriLimit](./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 | 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,
  },
})
```




---
url: /api/rspeedy/rspeedy.output.distpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [distPath](./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.distpath.intermediate.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [DistPath](./rspeedy.distpath.md) &gt; [intermediate](./rspeedy.distpath.intermediate.md)

## DistPath.intermediate property

The output directory of the intermediate files.

**Signature:**

```typescript
intermediate?: string | undefined;
```

## Remarks

Default value:

- `'.rspeedy'`




---
url: /api/rspeedy/rspeedy.output.filename.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [filename](./rspeedy.output.filename.md)

## Output.filename property

The [Filename](./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](./rspeedy.filename.bundle.md)<!-- -->.

## Example


```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    filename: '[name]/[name].lynx.bundle',
  },
})
```




---
url: /api/rspeedy/rspeedy.filename.bundle.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [bundle](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [css](./rspeedy.filename.css.md)

## Filename.css property

The name of the CSS files.

**Signature:**

```typescript
css?: string | undefined;
```

## Remarks

Default values:

- `'[name].css'`




---
url: /api/rspeedy/rspeedy.filename.font.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [font](./rspeedy.filename.font.md)

## Filename.font property

The name of the font files.

**Signature:**

```typescript
font?: string | 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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [image](./rspeedy.filename.image.md)

## Filename.image property

The name of non-SVG images.

**Signature:**

```typescript
image?: string | 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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [js](./rspeedy.filename.js.md)

## Filename.js property

The name of the JavaScript files.

**Signature:**

```typescript
js?: string | undefined;
```

## Remarks

Default values:

- Development: `'[name].js'` - Production: `'[name].[contenthash:8].js'`




---
url: /api/rspeedy/rspeedy.filename.media.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [media](./rspeedy.filename.media.md)

## Filename.media property

The name of media assets, such as video.

**Signature:**

```typescript
media?: string | 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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [svg](./rspeedy.filename.svg.md)

## Filename.svg property

The name of the SVG images.

**Signature:**

```typescript
svg?: string | 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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Filename](./rspeedy.filename.md) &gt; [template](./rspeedy.filename.template.md)

## Filename.template property

> Warning: This API is now obsolete.
> 
> Use [Filename.bundle](./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.output.filenamehash.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [filenameHash](./rspeedy.output.filenamehash.md)

## Output.filenameHash property

The [Output.filenameHash](./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](./rspeedy.output.filename.md) has a higher priority than [Output.filenameHash](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [inlineScripts](./rspeedy.output.inlinescripts.md)

## Output.inlineScripts property

The [Output.inlineScripts](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [legalComments](./rspeedy.output.legalcomments.md)

## Output.legalComments property

The [Output.legalComments](./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.minify.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [minify](./rspeedy.output.minify.md)

## Output.minify property

The [Minify](./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.minify.css.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Minify](./rspeedy.minify.md) &gt; [css](./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.js.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Minify](./rspeedy.minify.md) &gt; [js](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Minify](./rspeedy.minify.md) &gt; [jsOptions](./rspeedy.minify.jsoptions.md)

## Minify.jsOptions property

[Minify.jsOptions](./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.output.sourcemap.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Output](./rspeedy.output.md) &gt; [sourceMap](./rspeedy.output.sourcemap.md)

## Output.sourceMap property

The [SourceMap](./rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

**Signature:**

```typescript
sourceMap?: boolean | SourceMap | undefined;
```



---
url: /api/rspeedy/rspeedy.sourcemap.js.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [SourceMap](./rspeedy.sourcemap.md) &gt; [js](./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.performance.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Performance](./rspeedy.performance.md)

## Performance interface

The [Performance](./rspeedy.performance.md) option is used to

**Signature:**

```typescript
export interface Performance 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [buildCache?](./rspeedy.performance.buildcache.md) |  | [BuildCache](./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?](./rspeedy.performance.chunksplit.md) |  | [ChunkSplit](./rspeedy.chunksplit.md) \| [ChunkSplitBySize](./rspeedy.chunksplitbysize.md) \| [ChunkSplitCustom](./rspeedy.chunksplitcustom.md) \| undefined | _(Optional)_ [Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy. |
|  [printFileSize?](./rspeedy.performance.printfilesize.md) |  | PerformanceConfig\['printFileSize'\] \| undefined | <p>_(Optional)_ Whether to print the file sizes after production build.</p><p>[Performance.printFileSize](./rspeedy.performance.printfilesize.md)</p><p>See [Rsbuild - performance.printFileSize](https://rsbuild.dev/config/performance/print-file-size) for details.</p> |
|  [profile?](./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?](./rspeedy.performance.removeconsole.md) |  | boolean \| [ConsoleType](./rspeedy.consoletype.md)<!-- -->\[\] \| undefined | _(Optional)_ Whether to remove <code>console.[methodName]</code> in production build. |




---
url: /api/rspeedy/rspeedy.performance.buildcache.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Performance](./rspeedy.performance.md) &gt; [buildCache](./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.buildcache.builddependencies.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [BuildCache](./rspeedy.buildcache.md) &gt; [buildDependencies](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [BuildCache](./rspeedy.buildcache.md) &gt; [cacheDigest](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [BuildCache](./rspeedy.buildcache.md) &gt; [cacheDirectory](./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.performance.chunksplit.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Performance](./rspeedy.performance.md) &gt; [chunkSplit](./rspeedy.performance.chunksplit.md)

## Performance.chunkSplit property

[Performance.chunkSplit](./rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
chunkSplit?: ChunkSplit | ChunkSplitBySize | ChunkSplitCustom | undefined;
```



---
url: /api/rspeedy/rspeedy.chunksplit.override.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplit](./rspeedy.chunksplit.md) &gt; [override](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplit](./rspeedy.chunksplit.md) &gt; [strategy](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitBySize](./rspeedy.chunksplitbysize.md) &gt; [maxSize](./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.minsize.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitBySize](./rspeedy.chunksplitbysize.md) &gt; [minSize](./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.chunksplitcustom.splitchunks.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [ChunkSplitCustom](./rspeedy.chunksplitcustom.md) &gt; [splitChunks](./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.performance.printfilesize.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Performance](./rspeedy.performance.md) &gt; [printFileSize](./rspeedy.performance.printfilesize.md)

## Performance.printFileSize property

Whether to print the file sizes after production build.

[Performance.printFileSize](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Performance](./rspeedy.performance.md) &gt; [profile](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Performance](./rspeedy.performance.md) &gt; [removeConsole](./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.server.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Server](./rspeedy.server.md)

## Server interface

The [Server](./rspeedy.server.md) option changes the behavior of dev-server.

**Signature:**

```typescript
export interface Server 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [base?](./rspeedy.server.base.md) |  | string \| undefined | _(Optional)_ Configure the base path of the server. |
|  [headers?](./rspeedy.server.headers.md) |  | Record&lt;string, string \| string\[\]&gt; \| undefined | _(Optional)_ Adds headers to all responses. |
|  [host?](./rspeedy.server.host.md) |  | string \| undefined | _(Optional)_ Specify the host that the Rspeedy Server listens to. |
|  [port?](./rspeedy.server.port.md) |  | number \| undefined | _(Optional)_ Specify the port that the Rspeedy Server listens to. |
|  [strictPort?](./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.base.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Server](./rspeedy.server.md) &gt; [base](./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.headers.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Server](./rspeedy.server.md) &gt; [headers](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Server](./rspeedy.server.md) &gt; [host](./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.port.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Server](./rspeedy.server.md) &gt; [port](./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.strictport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Server](./rspeedy.server.md) &gt; [strictPort](./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.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md)

## Source interface

The [Source](./rspeedy.source.md) option changes the behavior of source files.

**Signature:**

```typescript
export interface Source 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [alias?](./rspeedy.source.alias.md) |  | Record&lt;string, string \| false \| string\[\]&gt; \| undefined | _(Optional)_ Create aliases to <code>import</code> or <code>require</code> certain modules more easily. |
|  [assetsInclude?](./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?](./rspeedy.source.decorators.md) |  | [Decorators](./rspeedy.decorators.md) \| undefined | _(Optional)_ Used to configure the decorators syntax. |
|  [define?](./rspeedy.source.define.md) |  | Record&lt;string, string \| number \| boolean \| undefined \| Record&lt;string, unknown&gt;&gt; \| undefined | _(Optional)_ The <code>define</code> options is used to define some values or expressions at compile time. |
|  [entry?](./rspeedy.source.entry.md) |  | [Entry](./rspeedy.entry.md) \| undefined | _(Optional)_ The [Entry](./rspeedy.entry.md) option is used to set the entry module. |
|  [exclude?](./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?](./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?](./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?](./rspeedy.source.transformimport.md) |  | [TransformImport](./rspeedy.transformimport.md)<!-- -->\[\] \| undefined | _(Optional)_ The [TransformImport](./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?](./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.alias.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [alias](./rspeedy.source.alias.md)

## Source.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({
  source: {
    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

`source.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({
  source: {
    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({
  source: {
    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 `source.alias` to `false` will ignore a module.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    alias: {
      'ignored-module': false,
      './ignored-module': false,
    },
  },
})
```




---
url: /api/rspeedy/rspeedy.source.assetsinclude.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [assetsInclude](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [decorators](./rspeedy.source.decorators.md)

## Source.decorators property

Used to configure the decorators syntax.

**Signature:**

```typescript
decorators?: Decorators | undefined;
```

## Remarks

See [Decorators.version](./rspeedy.decorators.version.md) for more information.




---
url: /api/rspeedy/rspeedy.decorators.version.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Decorators](./rspeedy.decorators.md) &gt; [version](./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.source.define.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [define](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [entry](./rspeedy.source.entry.md)

## Source.entry property

The [Entry](./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](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [exclude](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [include](./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.preentry.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [preEntry](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [transformImport](./rspeedy.source.transformimport.md)

## Source.transformImport property

The [TransformImport](./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.transformimport.cameltodashcomponentname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [TransformImport](./rspeedy.transformimport.md) &gt; [camelToDashComponentName](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [TransformImport](./rspeedy.transformimport.md) &gt; [customName](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [TransformImport](./rspeedy.transformimport.md) &gt; [libraryDirectory](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [TransformImport](./rspeedy.transformimport.md) &gt; [libraryName](./rspeedy.transformimport.libraryname.md)

## TransformImport.libraryName property

The original import path that needs to be transformed.

**Signature:**

```typescript
libraryName: string;
```

## Remarks

This option is required.




---
url: /api/rspeedy/rspeedy.transformimport.transformtodefaultimport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [TransformImport](./rspeedy.transformimport.md) &gt; [transformToDefaultImport](./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.source.tsconfigpath.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Source](./rspeedy.source.md) &gt; [tsconfigPath](./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](./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.tools.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Tools](./rspeedy.tools.md)

## Tools interface

The [Tools](./rspeedy.tools.md) options changes the behavior of various building tools.

**Signature:**

```typescript
export interface Tools 
```

## Properties

|  Property | Modifiers | Type | Description |
|  --- | --- | --- | --- |
|  [bundlerChain?](./rspeedy.tools.bundlerchain.md) |  | ToolsConfig\['bundlerChain'\] \| undefined | _(Optional)_ The [Tools.bundlerChain](./rspeedy.tools.bundlerchain.md) changes the options of [Rspack](https://www.rspack.dev) using [rspack-chain](https://github.com/rspack-contrib/rspack-chain)<!-- -->. |
|  [cssExtract?](./rspeedy.tools.cssextract.md) |  | [CssExtract](./rspeedy.cssextract.md) \| undefined | _(Optional)_ The [CssExtract](./rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin) |
|  [cssLoader?](./rspeedy.tools.cssloader.md) |  | [CssLoader](./rspeedy.cssloader.md) \| undefined | _(Optional)_ The [CssLoader](./rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->. |
|  [rsdoctor?](./rspeedy.tools.rsdoctor.md) |  | [RsdoctorRspackPluginOptions](./rspeedy.rsdoctorrspackpluginoptions.md) \| undefined | _(Optional)_ The [Tools.rsdoctor](./rspeedy.tools.rsdoctor.md) controls the options of [Rsdoctor](https://rsdoctor.dev/)<!-- -->. |
|  [rspack?](./rspeedy.tools.rspack.md) |  | ToolsConfig\['rspack'\] \| undefined | _(Optional)_ The [Tools.rspack](./rspeedy.tools.rspack.md) controls the options of [Rspack](https://www.rspack.dev/)<!-- -->. |
|  [swc?](./rspeedy.tools.swc.md) |  | ToolsConfig\['swc'\] \| undefined | _(Optional)_ The [Tools.swc](./rspeedy.tools.swc.md) controls the options of [builtin:swc-loader](https://rspack.dev/guide/features/builtin-swc-loader)<!-- -->. |




---
url: /api/rspeedy/rspeedy.tools.bundlerchain.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Tools](./rspeedy.tools.md) &gt; [bundlerChain](./rspeedy.tools.bundlerchain.md)

## Tools.bundlerChain property

The [Tools.bundlerChain](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Tools](./rspeedy.tools.md) &gt; [cssExtract](./rspeedy.tools.cssextract.md)

## Tools.cssExtract property

The [CssExtract](./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.cssextract.loaderoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtract](./rspeedy.cssextract.md) &gt; [loaderOptions](./rspeedy.cssextract.loaderoptions.md)

## CssExtract.loaderOptions property

The options of CSS extract loader.

**Signature:**

```typescript
loaderOptions?: CssExtractRspackLoaderOptions | undefined;
```



---
url: /api/rspeedy/rspeedy.cssextractrspackloaderoptions.esmodule.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtractRspackLoaderOptions](./rspeedy.cssextractrspackloaderoptions.md) &gt; [esModule](./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.cssextract.pluginoptions.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtract](./rspeedy.cssextract.md) &gt; [pluginOptions](./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.cssextractrspackpluginoptions.ignoreorder.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtractRspackPluginOptions](./rspeedy.cssextractrspackpluginoptions.md) &gt; [ignoreOrder](./rspeedy.cssextractrspackpluginoptions.ignoreorder.md)

## CssExtractRspackPluginOptions.ignoreOrder property


**Signature:**

```typescript
ignoreOrder?: boolean | undefined;
```



---
url: /api/rspeedy/rspeedy.cssextractrspackpluginoptions.pathinfo.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssExtractRspackPluginOptions](./rspeedy.cssextractrspackpluginoptions.md) &gt; [pathinfo](./rspeedy.cssextractrspackpluginoptions.pathinfo.md)

## CssExtractRspackPluginOptions.pathinfo property


**Signature:**

```typescript
pathinfo?: boolean | undefined;
```



---
url: /api/rspeedy/rspeedy.tools.cssloader.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Tools](./rspeedy.tools.md) &gt; [cssLoader](./rspeedy.tools.cssloader.md)

## Tools.cssLoader property

The [CssLoader](./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.cssloader.importloaders.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoader](./rspeedy.cssloader.md) &gt; [importLoaders](./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.modules.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoader](./rspeedy.cssloader.md) &gt; [modules](./rspeedy.cssloader.modules.md)

## CssLoader.modules property

The [cssLoader.modules](./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](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoaderModules](./rspeedy.cssloadermodules.md) &gt; [auto](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoaderModules](./rspeedy.cssloadermodules.md) &gt; [exportLocalsConvention](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoaderModules](./rspeedy.cssloadermodules.md) &gt; [localIdentName](./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

See [css-loader\#localIdentName](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#localIdentName) for details.




---
url: /api/rspeedy/rspeedy.cssloadermodules.namedexport.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [CssLoaderModules](./rspeedy.cssloadermodules.md) &gt; [namedExport](./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.tools.rsdoctor.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Tools](./rspeedy.tools.md) &gt; [rsdoctor](./rspeedy.tools.rsdoctor.md)

## Tools.rsdoctor property

The [Tools.rsdoctor](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Tools](./rspeedy.tools.md) &gt; [rspack](./rspeedy.tools.rspack.md)

## Tools.rspack property

The [Tools.rspack](./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](./index.md) &gt; [@lynx-js/rspeedy](./rspeedy.md) &gt; [Tools](./rspeedy.tools.md) &gt; [swc](./rspeedy.tools.swc.md)

## Tools.swc property

The [Tools.swc](./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/react-rsbuild-plugin.pluginreactlynx.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [pluginReactLynx](./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](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [compat](./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.compatvisitorconfig.addcomponentelement.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [addComponentElement](./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](./react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        addComponentElement: { compilerOnly: true }
      },
    })
  ],
})
```




---
url: /api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.compileronly.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [AddComponentElementConfig](./react-rsbuild-plugin.addcomponentelementconfig.md) &gt; [compilerOnly](./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](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [additionalComponentAttributes](./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](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [componentsPkg](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [darkMode](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [disableDeprecatedWarning](./react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md)

## CompatVisitorConfig.disableDeprecatedWarning property

Whether to disable deprecated warnings

**Signature:**

```typescript
disableDeprecatedWarning: boolean
```

## Remarks

Default value: `false`

## Example

Disable all the `DEPRECATED:` warnings.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        disableDeprecatedWarning: true
      },
    })
  ],
})
```




---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [newRuntimePkg](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [oldRuntimePkg](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [removeComponentAttrRegex](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [CompatVisitorConfig](./react-rsbuild-plugin.compatvisitorconfig.md) &gt; [simplifyCtorLikeReactLynx2](./react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md)

## CompatVisitorConfig.simplifyCtorLikeReactLynx2 property

> Warning: This API is now obsolete.
> 
> Using `simplifyCtorLikeReactLynx2` is not recommended as it introduces implicit behaviors that can:
> 
> - Make code harder to understand and maintain
> 
> - Create hidden dependencies between components
> 
> - Complicate debugging and testing processes
> 
> Instead, use `background-only` on class methods for explicit and maintainable behavior
> 

Whether to simplify constructor calls like ReactLynx 2

**Signature:**

```typescript
simplifyCtorLikeReactLynx2: boolean
```

## Remarks

Default value: `false`

## Example


```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        simplifyCtorLikeReactLynx2: true
      },
    })
  ],
})
```




---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [customCSSInheritanceList](./react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md)

## PluginReactLynxOptions.customCSSInheritanceList property

When [PluginReactLynxOptions.enableCSSInheritance](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [debugInfoOutside](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [defaultDisplayLinear](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [defineDCE](./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.definedcevisitorconfig.define.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [DefineDceVisitorConfig](./react-rsbuild-plugin.definedcevisitorconfig.md) &gt; [define](./react-rsbuild-plugin.definedcevisitorconfig.define.md)

## DefineDceVisitorConfig.define property

Replaces variables in your code with other values or expressions at compile time.

**Signature:**

```typescript
define: Record<string, string>
```

## Remarks

Caveat: differences between `source.define`

`defineDCE` happens before transforming `background-only` directives. So it's useful for eliminating code that is only used in the background from main-thread.

## Example


```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      defineDCE: {
        define: {
          __FOO__: 'false',
          'process.env.PLATFORM': '"lynx"',
        },
      },
    })
  ],
})
```
Then, `__FOO__` and `process.env.PLATFORM` could be used in source code.

```
if (process.env.PLATFORM === 'lynx') {
  console.log('lynx')
}

function FooOrBar() {
  if (__FOO__) {
    return <text>foo</text>
  } else {
    return <text>bar</text>
  }
}
```




---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableAccessibilityElement](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableCSSInheritance](./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](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableCSSInvalidation](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableCSSSelector](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableICU](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableNewGesture](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableParallelElement](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableRemoveCSSScope](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [enableSSR](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [engineVersion](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [experimental\_isLazyBundle](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [extractStr](./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.extractstrconfig.strlength.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [ExtractStrConfig](./react-rsbuild-plugin.extractstrconfig.md) &gt; [strLength](./react-rsbuild-plugin.extractstrconfig.strlength.md)

## ExtractStrConfig.strLength property

The minimum length of string literals to be extracted.

**Signature:**

```typescript
strLength: number
```

## Remarks

Default value: `20`<!-- -->.

## Example


```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      extractStr: {
        strLength: 10,
      },
    })
  ],
})
```




---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.firstscreensynctiming.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [firstScreenSyncTiming](./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.pipelineschedulerconfig.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [pipelineSchedulerConfig](./react-rsbuild-plugin.pluginreactlynxoptions.pipelineschedulerconfig.md)

## PluginReactLynxOptions.pipelineSchedulerConfig property

Composite configuration representing pipeline scheduling strategies, including [PluginReactLynxOptions.enableParallelElement](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [removeDescendantSelectorScope](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [shake](./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.shakevisitorconfig.pkgname.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [ShakeVisitorConfig](./react-rsbuild-plugin.shakevisitorconfig.md) &gt; [pkgName](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [ShakeVisitorConfig](./react-rsbuild-plugin.shakevisitorconfig.md) &gt; [removeCallParams](./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](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [ShakeVisitorConfig](./react-rsbuild-plugin.shakevisitorconfig.md) &gt; [retainProp](./react-rsbuild-plugin.shakevisitorconfig.retainprop.md)

## ShakeVisitorConfig.retainProp property

Properties that should be retained in the component class

**Signature:**

```typescript
retainProp: Array<string>
```

## Remarks

Default value: `['constructor', 'render', 'getDerivedStateFromProps', 'state', 'defaultDataProcessor', 'dataProcessors', 'contextType', 'defaultProps']` The provided values will be merged with the default values instead of replacing them.

## Example


```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        retainProp: ['myCustomMethod']
      }
    })
  ]
})
```




---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/react-rsbuild-plugin](./react-rsbuild-plugin.md) &gt; [PluginReactLynxOptions](./react-rsbuild-plugin.pluginreactlynxoptions.md) &gt; [targetSdkVersion](./react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md)

## PluginReactLynxOptions.targetSdkVersion property

> Warning: This API is now obsolete.
> 
> `targetSdkVersion` is now an alias of [PluginReactLynxOptions.engineVersion](./react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md)<!-- -->. Use [PluginReactLynxOptions.engineVersion](./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/qrcode-rsbuild-plugin.customizedschemafn.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/qrcode-rsbuild-plugin](./qrcode-rsbuild-plugin.md) &gt; [CustomizedSchemaFn](./qrcode-rsbuild-plugin.customizedschemafn.md)

## CustomizedSchemaFn type

Customize the generated schema.

**Signature:**

```typescript
export type CustomizedSchemaFn = (url: string) => string | Record<string, string>;
```



---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/qrcode-rsbuild-plugin](./qrcode-rsbuild-plugin.md) &gt; [pluginQRCode](./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](./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.schema.md
---

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@lynx-js/qrcode-rsbuild-plugin](./qrcode-rsbuild-plugin.md) &gt; [PluginQRCodeOptions](./qrcode-rsbuild-plugin.pluginqrcodeoptions.md) &gt; [schema](./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/elements/built-in/view.md
---



# `<view>`



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

### As a Layout Container

## 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`](/en/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`&#x20;

```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](/en/api/lynx-api/event/event.md#target).

### `flatten`&#x20;

```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/anti-exposure events](/en/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.

Before using this capability, you also need to set [`enable-exposure-ui-margin`](#enable-exposure-ui-margin) for the current node.

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

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

Setting it to `true` will change the behavior of [`exposure-screen-margin-*`](#exposure-screen-margin-) and may cause the lazy loading of the scrollable container to fail.

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

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

### `native-interaction-enabled`

```ts
// DefaultValue: true for iOS, 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 side, only supports setting effectiveness on the `view` element.

Known differences between the two sides: Android supports platform-layer gesture penetration/interception of parent-child/sibling structures; iOS only supports platform-layer gesture penetration/interception of sibling structures.
:::

### `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](/en/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?: number [number []]
```

Specify whether to block platform layer gestures outside Lynx when the target node is on the [event response chain](/en/guide/interaction/event-handling/event-propagation.md#event-response-chain) and the touch is in the specified area of ​​the target node, which can achieve a similar effect of blocking the platform layer side sliding back.

The inner array is an array containing `4` numbers, namely `x`, `y`, `width`, `height`, indicating the position of the touch area in the target node.

### `consume-slide-event`

```ts
// DefaultValue: []
consume-slide-event?: number [number []]
```

Specify the target node to slide a specific angle on the [event response chain](/en/guide/interaction/event-handling/event-propagation.md#event-response-chain), whether the platform layer gesture responds, does not affect the touch event of Lynx, and can realize a front-end scrolling container similar to consuming the specified direction of sliding.

The inner array is an array containing 2 numbers, namely `start` and `end`, indicating the starting angle and the ending angle.

### `event-through`

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

Specifies whether the touch event of the platform layer is distributed to Lynx when the touch is on the target node, which can achieve a similar effect of only displaying without interaction. This property supports inheritance.

This property can only ensure that Lynx does not consume the touch event of the platform layer, but the parent view of LynxView may consume the touch event, resulting in failure of penetration.

### `enable-touch-pseudo-propagation`

```ts
// DefaultValue: false
enable-touch-pseudo-propagation?: boolean
```

Specify whether the target node supports the `:active` pseudo-class to continue bubbling up on the [event response chain](/en/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.

:::tip
Other factors with higher priority may cause the hot zone modification to fail, such as the node's view hierarchy ([`z-index`](/en/api/css/properties/z-index.md), [`translateZ`](/en/api/css/properties/transform.md), [`fixed`](/en/api/css/properties/position.md#fixed)) is relatively high, the parent node's [`overflow`](/en/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.

In addition, it also supports inheritance, that is, the default value of the child node is the `ignore-focus` value of the parent node, and the child node can override this value.

### `ios-enable-simultaneous-touch`&#x20;

```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](/en/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.md).For more detailed usage, see the [Marking Lynx Pipeline](/guide/performance/timing-flag.md).

## Events

The front end can set [event handler property](/en/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](/en/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](/en/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](/en/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](/en/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](/en/api/lynx-api/event/touch-event.md), which is triggered when the finger clicks on the touch surface.

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](/en/api/lynx-api/event/touch-event.md), which is triggered when the finger is long pressed on the touch surface, and the interval between long press triggers is `500 ms`.

### `layoutchange`

```ts
layoutchange: LayoutChangeDetailEvent;
```

It belongs to [custom event](/en/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](/en/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](/en/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](/en/api/lynx-api/event/animation-event.md), which is triggered when the Animation animation starts.

### `animationend`

```ts
animationend: AnimationEvent;
```

It belongs to [animation event](/en/api/lynx-api/event/animation-event.md), which is triggered when the Animation animation ends.

### `animationcancel`

```ts
animationcancel: AnimationEvent;
```

It belongs to [animation event](/en/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](/en/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](/en/api/lynx-api/event/animation-event.md), which is triggered when the Transition animation starts.

### `transitionend`

```ts
transitionend: TransitionEvent;
```

It belongs to [animation event](/en/api/lynx-api/event/animation-event.md), which is triggered when the Transition animation ends.

### `transitioncancel`

```ts
transitioncancel: TransitionEvent;
```

It belongs to [animation event](/en/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: {
      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.
    },
    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.

When used on Android, you need to set [`flatten`](#flatten) to `false` on the corresponding node.
:::

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




---
url: /api/elements/built-in/text.md
---



# `<text>`

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

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.

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

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

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

:::

## 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`&#x20;

```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/resource-fetcher/GenericResourceFetcher.md) to download web font resources.

### Implementing Android Resource Loader

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

    ...
  }
}

//Inject during `LynxView` construction.
LynxViewBuilder.setGenericResourceFetcher(new ExampleGenericResourceFetcher(context));
```

### Implementing iOS Resource Loader

```objective-c
@interface ExampleGenericResourceFetcher : NSObject <LynxGenericResourceFetcher>

- (void)fetchResource:(LynxResourceRequest *)request
           onComplete:(LynxGenericResourceCompletionBlock)callback;

@end

@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

//Inject during `LynxView` construction.
LynxViewBuilder.genericResourceFetcher = [[ExampleGenericResourceFetcher alloc] init];
```

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

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

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

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

### Nested `<text>`

### nested `<image>`

### `<inline-truncation>`



---
url: /api/elements/built-in/image.md
---

# `<image>`



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

### Adding borders, rounded corners, and backgrounds to the image

You can set the image's borders, rounded corners, and background colors using CSS styles.

### Adding special drawing effects to the image

Supports special drawing effects like Gaussian blur.

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

### Listening to image load success/failure

You can bind [events](/api/elements/built-in/image.md#events) to listen for the image load state.

## Properties

### `src`  \{#required-src}

```tsx
src: string;
```

Specifies the image [URL](https://developer.mozilla.org/en-US/docs/Glossary/URL) to display.

The supported image formats are: `png`, `jpg`, `jpeg`, `bmp`, `gif`, and `webp`.

`svg` format is currently not supported. If you need to render `svg` images, you can refer to [Custom Element](/en/guide/custom-native-component.md) to implement it yourself.

::: note

For front-end built-in resources, please refer to [static resource handling](/en/rspeedy/assets.md) for configuration, or the image may not display correctly after deployment.

:::

### `mode`

```tsx
// DefaultValue: 'scaleToFill'
mode?: 'scaleToFill' | 'aspectFit' | 'aspectFill';
```

Specifies the image cropping/scaling mode:

* `scaleToFill` (default): The image is stretched to fill the `<image>` element without maintaining its aspect ratio.
* `aspectFit`: Scales the image to maintain its aspect ratio, ensuring the entire image is visible.
* `aspectFill`: Scales the image to maintain its aspect ratio, causing the shorter side to fill the `<image>` element, which may crop part of the image.

### `placeholder`

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

Specifies the path to the placeholder image. The usage and limitations are the same as for the `src` attribute.

### `blur-radius`

```tsx
// DefaultValue: '0px'
blur-radius?: string;
```

Specifies the Gaussian blur radius for the image.

### `prefetch-width/prefetch-height`

```tsx
// DefaultValue: '0px'
prefetch-width/prefetch-height?: string;
```

Allows initiating a request when the image has a width/height of 0. This is typically used when preloading images. It's recommended to set the sizes to match the actual layout width/height.

### `cap-insets`

```tsx
// DefaultValue: '0px 0px 0px 0px'
cap-insets?: string;
```

Specifies the 9patch image scaling area with four values representing the top, right, bottom, and left edges. Values must be specific numbers and do not support percentages or decimals.

```tsx
// Specifies the pixel range starting from [14 * ${cap-insets-scale}, imageWidth - 14 * ${cap-insets-scale}] for stretching the image.
cap-insets="0px 14px 0 14px"
```

:::note

Using `cap-insets` does not require the original image to be a [9patch](https://developer.android.com/studio/write/draw9patch) image.

:::

### `cap-insets-scale`

```tsx
// DefaultValue: 1
cap-insets-scale?: number;
```

Works with `cap-insets` to adjust the pixel positions when stretching the image.

### `loop-count`

```tsx
// DefaultValue: 0
loop-count?: number;
```

Specifies the number of times to play an animated image. The default is to loop indefinitely.

### `image-config`&#x20;

```tsx
// DefaultValue: 'ARGB_8888'
image-config?: 'RGB_565' | 'ARGB_8888';
```

Specifies the image data format. There are two options:

* `ARGB_8888`: Each pixel uses 32 bits of memory, including an alpha channel for transparency.
* `RGB_565`: Each pixel uses 16 bits of memory, which reduces memory usage but loses transparency.

::: note

This affects the actual memory size of the bitmap on Android.

For an image with a resolution of 1024x768, the memory size used would be calculated as: (1024 \_ 768 \_ pixel bits / 8) bytes.
:::

### `auto-size`

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

### `defer-src-invalidation`

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

### `autoplay`

```tsx
// DefaultValue: true
autoplay?: boolean;
```

Specifies whether the animated image should start playing automatically once it is loaded. The default is to autoplay.

### `tint-color`

```tsx
tint-color?: string;
```

Changes the color of all non-transparent pixels to the `tint-color` specified. The value is a [color](/api/css/data-type/color.md).

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindload`

Triggered when the image request succeeds, outputting the image's width and height.

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

interface ImageLoadEvent {
  detail: {
    width: number;
    height: number;
  };
}
```

### `binderror`

Triggered when the image request fails, outputting the error message and code.

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

interface ImageErrorEvent {
  detail: {
    errMsg: string; // Error message
    error_code: number;
    lynx_categorized_code: number;
  };
}
```

## Methods

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

### `startAnimate`

```ts

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'startAnimate'，
    })
    .exec();

```

Restarts the animation. The animation progress and loop-count are both reset.

### `pauseAnimation`

```ts

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'pauseAnimation'，
    })
    .exec();

```

Pauses the animation, without resetting the loop-count.

### `resumeAnimation`

```ts

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'resumeAnimation'，
    })
    .exec();

```

Resumes the animation, without resetting the loop-count.

### `stopAnimation`

```ts

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'stopAnimation'，
    })
    .exec();

```

Stops the animation, resetting 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/resource-fetcher/MediaResourceFetcher.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:

```objective-c
/// Local resource handler header
#import <LynxMediaResourceFetcher/LynxMediaResourceFetcher.h>

@interface LocalMediaFetcher : NSObject <LynxMediaResourceFetcher>

- (NSString *)shouldRedirectUrl:(LynxResourceRequest *)request;

- (LynxResourceOptionalBool)isLocalResource:(NSURL *)url;

@end
```

```objective-c
/// Local resource handler implementation
#import "LocalMediaFetcher.h"

@implementation LocalMediaFetcher

/**
 * Resource path conversion method
 * @param request Resource request object
 * @return Local file path or empty string
 */
- (NSString *)shouldRedirectUrl:(LynxResourceRequest *)request {
  NSURL *url = [NSURL URLWithString:request.url];
  NSString *fileType = [url pathExtension];
  NSString *fileName = [[url URLByDeletingPathExtension] lastPathComponent];
  NSString *subdir = [[[url URLByDeletingLastPathComponent] absoluteString] stringByReplacingOccurrencesOfString:@"http://localhost" withString:@""];
  NSString *path = [[NSBundle mainBundle] pathForResource:fileName ofType:fileType inDirectory:subdir];
  return path ? [NSString stringWithFormat:@"file://%@", path] : @"";
}

/**
 * Local resource detection method
 * @param url The original request URL
 * @return LynxResourceOptionalBoolTrue indicates the request needs redirection
 */
- (LynxResourceOptionalBool)isLocalResource:(NSURL *)url {
    return [url.absoluteString hasPrefix:@"http://localhost"] ?
           LynxResourceOptionalBoolTrue :
           LynxResourceOptionalBoolFalse;
}

@end
```

```java
import com.lynx.tasm.resourceprovider.LynxResourceRequest
import com.lynx.tasm.resourceprovider.media.LynxMediaResourceFetcher
import com.lynx.tasm.resourceprovider.media.OptionalBool

/**
 * Custom media resource handler
 *
 * @property protocol The protocol to intercept "http://localhost"
 * @property scheme The target resource protocol "asset://"
 */
class LocalMediaFetcher : LynxMediaResourceFetcher() {

    /**
     * Determines if the resource is local
     * @param url The original request URL
     * @return OptionalBool.TRUE indicates the request needs redirection
     */
    override fun isLocalResource(url: String?): OptionalBool {
        return if (url?.startsWith("http://localhost") == true) {
            OptionalBool.TRUE
        } else {
            OptionalBool.FALSE
        }
    }

    /**
     * Performs URL redirection
     * @param request The resource request object
     * @return The converted valid resource path
     */
    override fun shouldRedirectUrl(request: LynxResourceRequest?): String {
        return request?.url?.replace(
            oldValue = "http://localhost",
            newValue = "asset://",
            ignoreCase = true
        ) ?: ""
    }
}
```

Read the API reference of [`MediaResourceFetcher`](/api/lynx-native-api/resource-fetcher/MediaResourceFetcher.md) for more details.

## Compatibility




---
url: /api/elements/built-in/scroll-view.md
---





# `<scroll-view>`

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.

### Scroll Events

Use event callbacks such as [`bindscroll`](#bindscroll), [`bindscrolltoupper`](#bindscrolltoupper), and [`bindscrolltolower`](#bindscrolltolower) to monitor changes in scroll progress.

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

:::tip
`sticky` can only be set for direct child nodes of `<scroll-view>`. On , 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

Attribute names and values describe the behavior and appearance of the component.

### `scroll-orientation`

```ts
// DefaultValue: "vertical"
scroll-orientation?: string
```

set scroll orientation for the scrollable container.

| 值         | 说明                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------- |
| vertical   | Child nodes are arranged vertically, causing `<scroll-view>` itself to scroll vertically     |
| horizontal | Child nodes are arranged horizontally, causing `<scroll-view>` itself to scroll horizontally |

### `enable-scroll`

```ts
// DefaultValue: true
enable-scroll?: boolean
```

Sets whether to allow gesture dragging to scroll. Supports dynamic switching and takes effect on the next gesture. When scrolling is disabled, the user cannot scroll manually.

| Value | Description                                                                                                  |
| ----- | ------------------------------------------------------------------------------------------------------------ |
| true  | User gestures can trigger scrolling                                                                          |
| false | User gestures cannot trigger scrolling but scrolling methods (e.g., `scrollTo`) can still initiate scrolling |

### `initial-scroll-offset`

```ts
// DefaultValue: N/A
initial-scroll-top?: string = ${number}px
```

Sets the **absolute** content offset distance during initial rendering (different from the `offset` concept in the `scrollTo` method). The horizontal or vertical direction is determined by `scroll-orientation`, and it only takes effect during the first `render` execution, not responding to subsequent changes.

:::tip
**Cannot be used simultaneously with `initial-scroll-offset/to-index` as they will cover each other.**
:::

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

```ts
// DefaultValue: N/A
initial-scroll-to-index?: string = ${number}px
```

Sets the child node to be positioned during initial rendering, only taking effect during the first `render` execution and not responding to subsequent changes.

:::tip
**Cannot be used simultaneously with `initial-scroll-offset/to-index` as they will cover each other.**

If the `index` is invalid (e.g., negative or exceeds the number of child nodes), the setting is ineffective.
:::

### `bounces`&#x20;

```ts
// DefaultValue: true
bounces?: boolean
```

Enables edge bounce effect.

### `upper-threshold`

```ts
// DefaultValue: N/A
upper-threshold?: string = ${number}px
```

Sets a scroll threshold (unit: `px`), indicating how far from the top or left before triggering the `scrolltoupper` event.

### `lower-threshold`

```ts
// DefaultValue: N/A
lower-threshold?: string = ${number}px
```

Sets a scroll threshold, indicating how far from the bottom or right before triggering the `scrolltolower` event.

### `scroll-bar-enable`

```ts
// DefaultValue: false
scroll-bar-enable?: boolean
```

Enables the scrollbar, supporting dynamic switching.

:::tip

&#x20;Only vertical scrolling has scrollbars.
<IOSOnly /> Supports both vertical and horizontal scrollbars. :::

## Events

Frontend can bind corresponding event callbacks to components to monitor their runtime behavior.

### `scroll`

```ts
bindscroll = (e: scrollEvent) => {};

interface scrollEvent extends CustomEvent {
  detail: {
    type: 'scroll'; // Event name
    deltaX: number; // Horizontal scroll offset since last scroll
    deltaY: number; // Vertical scroll offset since last scroll
    scrollLeft: number; // Current horizontal scroll offset
    scrollTop: number; // Current vertical scroll offset
    scrollHeight: number; // Current content height
    scrollWidth: number; // Current content width
  };
}
```

Triggered during scrolling (whether animated or not).

:::tip

If there is a bounce (`bounces={true}`), `scrollLeft` and `scrollTop` may be
negative during the bounce. :::

### `scrolltoupper`

```ts
bindscrolltoupper = (e: scrollToUpperEvent) => {};

interface scrollToUpperEvent extends CustomEvent {
  detail: {
    type: 'scrolltoupper'; // Event name
    deltaX: 0; // Default value
    deltaY: 0; // Default value
  };
}
```

Triggered when the defined [`upperThreshold`](#upperThreshold) area intersecting the visible area at the top or left.

### `scrolltolower`

```ts
bindscrolltolower = (e: scrollToLowerEvent) => {};

interface scrollToLowerEvent extends CustomEvent {
  detail: {
    type: 'scrolltolower'; // Event name
    deltaX: 0; // Default value
    deltaY: 0; // Default value
  };
}
```

Triggered when the defined [`lowerThreshold`](#lowerThreshold) area intersects the visible area at the bottom or right.

### `scrollend`

```ts
bindscrollend = (e: scrollEndEvent) => {};

interface scrollEndEvent extends CustomEvent {
  detail: {
    type: 'scrollend'; // Event name
    deltaX: 0; // Default value
    deltaY: 0; // Default value
    scrollLeft: number; // Current horizontal scroll offset
    scrollTop: number; // Current vertical scroll offset
    scrollHeight: number; // Current content height
    scrollWidth: number; // Current content width
  };
}
```

Triggered when scrolling ends.

### `contentsizechanged`

```ts
bindcontentsizechanged = (e: contentSizeChanged) => {};

interface contentSizeChanged extends CustomEvent {
  detail: {
    type: 'contentsizechanged'; // Event name
    scrollWidth: number; // New content width
    scrollHeight: number; // New content height
  };
}
```

Triggered when the content area comprised of direct child nodes changes in width or height. This event triggers after the `<scroll-view>` content completes layout. If updating `<scroll-view>` child nodes, call updated scrolling methods like [`scrollTo`](#scrollTo) in this event.

## Methods

Frontend can execute component methods through the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API, using the following methods:

```ts title=index.js
lynx
  .createSelectorQuery() // Create SelectorQuery
  .select('#video') // Specify target node selector
  .invoke({
    method: 'seekTo',
    params: {
      duration: 1000, // Operation parameters
    },
    success: function (res) {
      console.log(res);
    },
    fail: function (res) {
      console.log(res.code, res.data);
    },
  })
  .exec(); // Execute query
```

### `scrollTo`

```ts
<`<scroll-view>`id="scroll"/>
// Target scrolling position calculation: MIN(scrollable area, child(index).position + offset)
lynx.createSelectorQuery()
  .select(`#scroll`)
  .invoke({
    method: 'scrollTo',
    params: {
      offset: 0, // Absolute offset value
      index: 1, // Target child node, positions to list's padding distance if set to zero
      smooth: true // Whether to smoothly scroll
    },
  })
  .exec();
```

Positions the `<scroll-view>` content to a specific location, using either the child node index `index` or an absolute offset `offset`. For the `offset` parameter, positive is right, negative is left; in RTL mode, positive-negative reverses, positive is left, negative is right.

### `autoScroll`

```ts
<`<scroll-view>`id="scroll"/>

lynx.createSelectorQuery()
  .select(`#scroll`)
  .invoke({
     method: 'autoScroll',
      params: {
        rate: 120, // Scrolling speed, distance per second (unit: px/sec)
        start: true // Start or stop auto-scrolling
      },
  })
  .exec();
```

Triggers automatic scrolling. If the `rate` is too small, it may not scroll. Upon reaching the boundary, `autoScroll` will stop automatically. If the user drags in the opposite direction to a certain position and releases, `autoScroll` will not re-trigger auto-scrolling.

### `scrollIntoView`

```ts
<scroll-view>
  <text id="targetnode">"click me, scrollIntoView"</text>
</scroll-view>

lynx.createSelectorQuery()
  .select(`#targetnode`)
  .invoke({
    method: 'scrollIntoView',
    params: {
      scrollIntoViewOptions: {
        block: 'center', // Vertical alignment options: "start" aligns top | "center" centers | "end" aligns bottom
        inline: 'start', // Horizontal alignment options: "start" aligns left | "center" centers | "end" aligns right
        behavior: 'smooth', // "smooth" | "none" whether to animate scrolling
      },
    },
  })
  .exec();
```

Scrolls the `<scroll-view>` to the specified child node. This method is bound to any (direct/indirect) child node of `<scroll-view>`, not `<scroll-view>` itself.

### `scrollBy`

```ts
<`<scroll-view>`id="scrollview"/>

lynx.createSelectorQuery()
  .select('#scrollview')
  .invoke({
    method: 'scrollBy',
    params: {
      offset: number, // Scroll distance, unit: px
    },
    success(res) {
      console.log('succ ');
    },
    fail(res) {
      console.log('err ');
    },
}).exec();
```

Scrolls by the distance based on existing offsets, unit `px`.

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




---
url: /api/elements/built-in/list.md
---





# `<list>`

The `<list>` component is a high-performance scrollable container that optimizes performance and memory usage through element recycling and lazy loading. It supports horizontal and vertical scrolling with single-column, grid, and waterfall layouts, making it ideal for infinite-scroll feeds and similar use cases.

## Usage

### Single-Column Layout

**1. Set width and height**: The width and height of `<list>` represent the size of its viewport, so they need to be fixed values and cannot be expanded by internal content. Only child nodes visible in the visible area will be rendered.

**2. Set scroll direction and layout form**: Set the attribute [`scroll-orientation`](#scroll-orientation) to specify the layout and scroll direction, and set [`list-type`](#list-type) and [`span-count`](#span-count) to specify the layout form.

**3. Configure child nodes**: Use the `<list-item>` tag as a direct child node of `<list>` , and set [`item-key`](#item-key) and [`key`](#key) for `<list-item>`, ensuring they are consistent.

### Multi-Column Layout

**1. Set layout type and column count**: Set the layout type [`list-type`](#list-type) to `flow` (grid layout) or `waterfall` (waterfall layout), and set [`span-count`](#span-count) >= 2.

**2. Full-span child nodes in multi-column layout**: Set the [`full-span`](#full-span) attribute for `<list-item/>` to make it occupy a full row or column in the layout.

Grid Layout Example:

Waterfall Layout Example:

## Attributes

### `list-type`  \{#required-list-type}

```tsx
list-type: 'single' | 'flow' | 'waterfall'
```

Controls the layout type of the `<list>` component, which needs to be used in conjunction with [`span-count`](#span-count).

| Value       | Description                                                                                                                                                                                                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `single`    | Single-column/row layout                                                                                                                                                                                                                                                                    |
| `flow`      | Multi-column/row grid layout. The grid layout fully reflects regularity, with the `top` of adjacent child nodes in columns being consistent. Typically used for child nodes of uniform size. The width of child nodes is determined by the width of `<list>` and `span-count`.              |
| `waterfall` | Multi-column/row waterfall layout. Content is continuously filled from top to bottom into the shortest column, achieving visual continuity and dynamism. Typically used for child nodes of varying sizes. The width of child nodes is determined by the width of `<list>` and `span-count`. |

You can find real world examples in the [Multi-Column Layout](#multi-column-layout) section to see the difference between `flow` and `waterfall` more clearly.

### `span-count`  \{#required-span-count}

```tsx
span-count: number
```

Sets the number of columns or rows for the `<list>` component layout.

### `scroll-orientation`  \{#required-scroll-orientation}

```tsx
// DefaultValue: "vertical"
scroll-orientation?: 'vertical' ｜ 'horizontal'
```

Sets the scrolling direction and layout direction of the `<list>` component.

### `item-key`  \{#required-item-key}

```tsx
// DefaultValue: null
item-key: string

<list-item item-key="item"/>
```

The `item-key` attribute is a required attribute on `<list-item>`.

:::note

Developers need to set a unique `item-key` for each `<list>` child node. It is used to help `<list>` identify which `<list>` child nodes have changed, been added, or removed. Therefore, developers need to ensure the correct setting of `item-key`. Incorrect settings may lead to disorder and flickering issues.

:::

### `key`  \{#required-key}

```tsx
// DefaultValue: null
key: string

<list-item
  item-key="item-0"
  key="item-0"
/>
```

Use the `key` attribute to help the framework identify which elements have changed, been added, or removed.

:::note

In the list scenario, `key` and `item-key` should remain consistent.

:::

### `enable-scroll`

```tsx
// DefaultValue: true
enable-scroll?: boolean
```

Indicates whether the `<list>` component is allowed to scroll.

### `enable-nested-scroll`

```tsx
// DefaultValue: true
enable-nested-scroll?: boolean
```

Indicates whether `<list>` can achieve nested scrolling with other scrollable containers. When enabled, the inner container scrolls first, followed by the outer container.

### `list-main-axis-gap`

```tsx
// DefaultValue: null
list-main-axis-gap?: ${number}px | ${number}rpx

<list
  style={{listMainAxisGap:'10px'}}
/>
```

Specifies the spacing of `<list>` child nodes in the main axis direction, which needs to be written in the style.

### `list-cross-axis-gap`

```tsx
// DefaultValue: null
list-cross-axis-gap?: ${number}px | ${number}rpx

<list
  style={{listCrossAxisGap:'10px'}}
/>
```

Specifies the spacing of `<list>` child nodes in the cross axis direction, which needs to be written in the style.

### `sticky`

```tsx
// DefaultValue: false
sticky?: boolean
```

Declared on the `<list>` component to control whether the `<list>` component as a whole is allowed to be sticky at the top or bottom.

### `sticky-offset`

```tsx
// DefaultValue: 0
sticky-offset?: number
```

The offset distance from the top or bottom of `<list>` for sticky positioning, in `px`.

### `sticky-top`

```tsx
// DefaultValue: false
sticky-top?: boolean
```

Declared on the `<list-item>` child node to control whether the node will be sticky at the top.

### `sticky-bottom`

```tsx
// DefaultValue: false
sticky-bottom?: boolean
```

Declared on the `<list-item>` child node to control whether the node will be sticky at the bottom.

### `bounces`&#x20;

```ts
// DefaultValue: true
bounces?: boolean
```

Enables edge bounce effect.

### `initial-scroll-index`

```tsx
// DefaultValue: 0
initial-scroll-index?: number
```

Specifies the node position to which `<list>` automatically scrolls after rendering, effective only once.

### `need-visible-item-info`

```tsx
// DefaultValue: false
need-visible-item-info?: boolean
```

Controls whether the scroll event callback parameters include the position information of the currently rendering node. The scroll events include: [`scroll`](#scroll), [`scrolltoupper`](#scrolltoupper), [`scrolltolower`](#scrolltolower).

Scroll event callback parameter format:

```tsx
interface ListScrollInfo {
  // Horizontal scroll offset since the last scroll, in px
  deltaX: number;
  // Vertical scroll offset since the last scroll, in px
  deltaY: number;
  // Current horizontal scroll offset, in px
  scrollLeft: number;
  // Current vertical scroll offset, in px
  scrollTop: number;
  // Current content area width, in px
  scrollWidth: number;
  // Current content area height, in px
  scrollHeight: number;
  // `<list>` width, in px
  listWidth: number;
  // `<list>` height, in px
  listHeight: number;
  // Scroll event source
  eventSource: ListEventSource;
  // Position information of the currently rendering node
  attachedCells: [
    {
      id: number; // Node id
      itemKey: string; // Node item-key
      index: number; // Node index in list
      left: number; // Node left boundary position relative to list, in px
      top: number; // Node top boundary position relative to list, in px
      right: number; // Node right boundary position relative to list, in px
      bottom: number; // Node bottom boundary position relative to list, in px
    },
  ];
}
```

### `upper-threshold-item-count`

```tsx
// DefaultValue: 0
upper-threshold-item-count?: number
```

Triggers a [`scrolltoupper`](#scrolltoupper) event once when the number of remaining displayable child nodes at the top of `<list>` is less than [`upper-threshold-item-count`](#upper-threshold-item-count) for the first time.

### `lower-threshold-item-count`

```tsx
// DefaultValue: 0
lower-threshold-item-count?: number
```

Triggers a [`scrolltolower`](#scrolltolower) event once when the number of remaining displayable child nodes at the bottom of `<list>` is less than [`lower-threshold-item-count`](#lower-threshold-item-count) for the first time.

### `scroll-event-throttle`

```tsx
// DefaultValue: 200
scroll-event-throttle?: number
```

Sets the time interval for the `<list>` callback [`scroll`](#scroll) event, in milliseconds (ms). By default, the scroll event is called back every 200 ms.

### `item-snap`

```tsx
// defaultValue: undefined
'item-snap'?: ListItemSnapAlignment;

interface ListItemSnapAlignment {
  factor: number;
  offset: number;
}
```

Controls the paginated scrolling effect of `<list>`.

Pagination parameters

* `factor`: The parameter for paginated positioning, with a range of `[0, 1]`
  * A value of `0` means the paginated scrolling `<list>` child node aligns with the top of `<list>`
  * A value of `1` means the paginated scrolling `<list>` child node aligns with the bottom of `<list>`
* `offset`: Additional offset parameter added on top of `factor`

:::note

When the 'engineVersion' version is less than '3.2', there will be inconsistencies in the scrolling speed on the mobile platform.

:::

### `need-layout-complete-info`

Controls whether the [`layoutcomplete`](#layoutcomplete) event includes the node layout information before and after this `layout`, the `<list>` Diff information that triggered this layout, and the current `<list>` scroll state information.

```tsx
export interface LayoutCompleteEvent extends BaseEvent<'layoutcomplete', {}> {
  detail: {
    'layout-id': number;
    // Enable need-layout-complete-info
    scrollInfo: ListScrollInfo;
    // Enable need-layout-complete-info
    diffResult?: {
      insertions: number[];
      move_from: number[];
      move_to: number[];
      removals: number[];
      update_from: number[];
      update_to: number[];
    };
    // Enable need-layout-complete-info
    visibleCellsAfterUpdate?: ListItemInfo[];
    // Enable need-layout-complete-info
    visibleCellsBeforeUpdate?: ListItemInfo[];
  };
}
```

### `layout-id`

```tsx
// defaultValue: -1
layout-id?: number
```

Used to mark the unique identifier for this data source update, which will be returned in the [`layoutcomplete`](#layoutcomplete) event callback.

### `preload-buffer-count`

```tsx
// DefaultValue: 0
preload-buffer-count?: number
```

This attribute controls the number of nodes outside `<list>` that are preloaded.

:::note

* The larger the value of `preload-buffer-count`, the more off-screen nodes can be preloaded, but it will also increase the memory usage of `<list>`.

* The recommended value for `preload-buffer-count` is the number of nodes that fill one screen of `<list>`.

* Only effective when `list-type='single'/'flow'`.

:::

### `scroll-bar-enable`&#x20;

```tsx
// DefaultValue: true
scroll-bar-enable?: boolean
```

Indicates whether the `<list>` component scroll bar is displayed.

### `reuse-identifier`

```tsx
// DefaultValue: null
reuse-identifier: string

<list>
  <list-item
    reuse-identifier="type1"
  >
  <list-item
    reuse-identifier="type2"
  >
</list>
```

Sets the reuse id for `<list-item>`. When rendering child nodes, the `<list>` component reuses `<list-item>` based on the `reuse-identifier` attribute value. Only `<list-item>` with the same `reuse-identifier` attribute value will be reused.

By default, developers do not need to provide a `reuse-identifier`, as the framework determines it during the compilation phase. For example, when `<list-item>` is within a loop (e.g., `Array.prototype.map`), since they have the same form and position during the compilation phase, we generate the same `reuse-identifier` for them, allowing this group of `<list-item>` to be reused with each other.

:::note

Use case: `<list-item>` with significant structural differences perform poorly when reused. Therefore, it is recommended to set different `reuse-identifier` values for them to avoid mutual reuse.

:::

### `full-span`

```tsx
// DefaultValue: false
full-span?: boolean
<list>
  <list-item full-span={true}/>
</list>
```

The `full-span` attribute is used to indicate that a `<list-item>` occupies a full row or column.

### `estimated-main-axis-size-px`

```tsx
// DefaultValue: -1
estimated-main-axis-size-px?: number
<list-item
  estimated-main-axis-size-px={100}
/>
```

Specifies the placeholder size in the main axis direction for `<list-item>` before it is fully rendered, in `px`. If not set, the default value is the size of `<list>` in the main axis direction.

:::note

It is strongly recommended that developers set `estimated-main-axis-size-px` to a value close to the actual size of the child nodes.

:::

## Events

Front-end developers can bind corresponding event callbacks to components to monitor runtime behavior. The usage is as follows.

### `scroll`

```tsx
bindscroll?: EventHandler<ListScrollEvent>;

interface ListScrollEvent {
  // Horizontal scroll offset since the last scroll, in px
  deltaX: number;
  // Vertical scroll offset since the last scroll, in px
  deltaY: number;
  // Current horizontal scroll offset, in px
  scrollLeft: number;
  // Current vertical scroll offset, in px
  scrollTop: number;
  // Current content area width, in px
  scrollWidth: number;
  // Current content area height, in px
  scrollHeight: number;
  // `<list>` width, in px
  listWidth: number;
  // `<list>` height, in px
  listHeight: number;
  // Scroll event source
  eventSource: ListEventSource;
  // Position information of the currently rendering node
  attachedCells: [
    {
      "id": number,        // Node id
      "itemKey": string,   // Node item-key
      "index": number,     // Node index in list
      "left": number,      // Node left boundary position relative to list, in px
      "top": number,       // Node top boundary position relative to list, in px
      "right": number,     // Node right boundary position relative to list, in px
      "bottom": number,    // Node bottom boundary position relative to list, in px
    },
  ];
}

enum ListEventSource {
  DIFF = 0,
  LAYOUT = 1,
  SCROLL = 2,
}
```

`<list>` scroll event.

:::note

* The frequency of scroll event triggers can be controlled by [`scroll-event-throttle`](#scroll-event-throttle).

* If `<list>` enables [`need-visible-item-info`](#need-visible-item-info), the callback parameters will include the position information of the currently rendering child nodes.

:::

### `scrolltoupper`

```tsx
bindscrolltoupper?: EventHandler<ListScrollEvent>;
```

Callback triggered when scrolling to the top of `<list>`. The trigger position of this callback can be controlled by [`upper-threshold-item-count`](#upper-threshold-item-count).

### `scrolltolower`

```tsx
bindscrolltolower?: EventHandler<ListScrollEvent>;
```

Callback triggered when scrolling to the bottom of `<list>`. The trigger position of this callback can be controlled by [`lower-threshold-item-count`](#lower-threshold-item-count).

### `scrollstatechange`

```tsx
bindscrollstatechange?: EventHandler<ListScrollStateChangeEvent>;

interface ScrollStateChangeEvent extends CustomEvent {
  detail: {
    // The scroll state of this slide, value description
    //   1 - Stationary
    //   2 - Dragging
    //   3 - Inertial scrolling
    //   4 - Smooth animation scrolling
    state: number;
  };
}
```

Callback triggered when the scroll state of `<list>` changes. The `state` field in the event parameter's `detail` indicates the scroll state: `1` for stationary, `2` for dragging, and `3` for inertial scrolling, `4` for smooth animation scrolling.

### `layoutcomplete`

```tsx
bindlayoutcomplete?: EventHandler<ListLayoutFinishEvent>;

interface LayoutCompleteEvent extends BaseEvent<'layoutcomplete', {}> {
  detail: {
    'layout-id': number;
    // Enable need-layout-complete-info
    scrollInfo: ListScrollInfo;
    // Enable need-layout-complete-info
    diffResult?: {
      insertions: number[];
      move_from: number[];
      move_to: number[];
      removals: number[];
      update_from: number[];
      update_to: number[];
    };
    // Enable need-layout-complete-info
    visibleCellsAfterUpdate?: ListItemInfo[];
    // Enable need-layout-complete-info
    visibleCellsBeforeUpdate?: ListItemInfo[];
  };
}

interface ListItemInfo {
  // Child node height
  height: number;
  // Child node width
  width: number;
  // Child node itemKey
  itemKey: string;
  // Whether the child node is in rendering state
  isBinding: boolean;
  // X coordinate position of the child node relative to the entire scroll area
  originX: number;
  // Y coordinate position of the child node relative to the entire scroll area
  originY: number;
  // Whether the child node has been updated
  updated: boolean;
}
```

Callback triggered after `<list>` layout is complete.

### `snap`

```tsx
bindsnap?: EventHandler<ListSnapEvent>;

interface ListSnapEvent extends common.BaseEvent<'snap', {}> {
  detail: {
    // The index of the node that will be paginated to
    position: number;
    // Current horizontal scroll offset, in px
    currentScrollLeft: number;
    // Current vertical scroll offset, in px
    currentScrollTop: number;
    // Target horizontal scroll offset for pagination, in px
    targetScrollLeft: number;
    // Target vertical scroll offset for pagination, in px
    targetScrollTop: number;
  };
};
```

Callback when pagination scrolling is about to occur.

## Methods

### `scrollToPosition`

```tsx
this.createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'scrollToPosition',
    params: {
      position: 10,
      offset: 100,
      alignTo: 'top',
      smooth: true,
    },
    success: function (res) {},
    fail: function (res) {},
  })
  .exec();
```

Scroll the `<list>` component to the specified position. Parameter description:

| Parameter | Type    | Default | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| :-------- | :------ | :------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| position  | number  | None    | Yes      | Specifies the index of the node to scroll to, with a range of `[0, data source count)`                                                                                                                                                                                                                                                                                                                                                                      |
| offset    | number  | None    | No       | After applying `alignTo` alignment, continue scrolling the `offset` length                                                                                                                                                                                                                                                                                                                                                                                  |
| alignTo   | string  | null    | Yes      | The position of the target node in the view after scrolling. `"bottom"`: Scroll until the node is fully visible in `<list>`, and the bottom of the node aligns with the bottom of `<list>``"top"`: Scroll until the node is fully visible in `<list>`, and the top of the node aligns with the top of `<list>``"middle"`: Scroll until the node is fully visible in `<list>`, and the node is vertically centered in `<list>` |
| smooth    | boolean | false   | No       | Whether there is animation during the scrolling process                                                                                                                                                                                                                                                                                                                                                                                                     |

### `autoScroll`

```tsx
this.createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'autoScroll',
    params: {
      rate: string, //  The distance scrolled per second, supports positive and negative. Distance supports units "px/rpx/ppx" default->null (iOS value must be greater than 1/screen.scale px)
      start: bool, //  Start/pause auto-scrolling default->false
      autoStop: bool, // Whether to automatically stop when reaching the bottom default->true
    },
    success: function (res) {},
    fail: function (res) {},
  })
  .exec();
```

Trigger `<list>` auto-scrolling. Parameter description:

| Parameter | Type   | Default | Required | Description                                                                                   |
| :-------- | :----- | :------ | :------- | :-------------------------------------------------------------------------------------------- |
| rate      | string | None    | null     | The distance scrolled per second, supports positive and negative, can set units: `px/rpx/ppx` |
| start     | bool   | None    | false    | Start or pause auto-scrolling, `true`: start auto-scrolling, `false`: pause auto-scrolling    |
| autoStop  | bool   | None    | true     | Whether to automatically stop when reaching the bottom                                        |

### `getVisibleCells`

```tsx
lynx
  .createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'getVisibleCells',
    success(res) {
      console.log('succ ');
    },
    fail(res) {
      console.log('err ');
    },
  })
  .exec();
```

Get information about all currently displayed `<list>` child nodes. The returned information is as follows:

```tsx
attachedCells: [
  {
    id: number, // Node id
    itemKey: string, // Node item-key
    index: number, // Node index in list
    left: number, // Node left boundary position relative to list, in px
    top: number, // Node top boundary position relative to list, in px
    right: number, // Node right boundary position relative to list, in px
    bottom: number, // Node bottom boundary position relative to list, in px
  },
];
```

### `scrollBy`

```tsx
lynx
  .createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'scrollBy',
    params: {
      offset: number,
    },
    success(res) {
      console.log('succ ');
    },
    fail(res) {
      console.log('err ');
    },
  })
  .exec();
```

Continue scrolling the distance specified by `offset` based on the existing offset, in `px`. The returned information is as follows:

```tsx
{
  "consumedX" : number,  // Distance scrolled horizontally, in px
  "consumedY" : number,  // Distance scrolled vertically, in px
  "unconsumedX" : number,  // Distance not scrolled horizontally, in px
  "unconsumedY" : number,  // Distance not scrolled vertically, in px
}
```

## More Features

### Sticky Elements

In the `<list>` component, you can achieve sticky top or sticky bottom node effects by setting the [`sticky-top`](#sticky-top) or [`sticky-bottom`](#sticky-bottom) attributes on `<list-item>`.

Ensure that the [`sticky`](#sticky) attribute of the `<list>` component is set to `true` to allow child nodes to be sticky. You can also set the [`sticky-offset`](#sticky-offet) to determine the sticky position.

```tsx
<list
  className="list-container"
  sticky={true}
  sticky-offset={50}
  list-type="single"
  span-count={1}
  scroll-orientation="vertical"
>
```

Set the [`sticky-top`](#sticky-top) or [`sticky-bottom`](#sticky-bottom) attributes on `<list-item>` to make the node sticky top or sticky bottom when scrolling. Since sticky nodes must be a full row item, you also need to set the [`full-span`](#full-span) attribute for the node.

```tsx
<list-item
  className="sticky-top-item"
  full-span={true}
  sticky-top={true}
  item-key={`list-item-${index}`}
  key={`list-item-${index}`}
/>
```

### Loading Content When Scrolling to Edge

The `<list>` component supports infinite scroll loading functionality through two key steps:

First, set an appropriate value for the [`lower-threshold-item-count`](#lower-threshold-item-count) attribute on the `<list>` component. This determines how close to the bottom the scroll needs to be before triggering the load more event. Then, bind the [`scrolltolower`](#scrolltolower) event handler which will be called when scrolling reaches the bottom threshold, allowing you to load additional data.

### Pagination with `item-snap`

Set the `factor` to determine the parameter for paginated scrolling positioning, with a range of `[0, 1]`. `0` means `<list-item>` aligns with the top of `<list>`, and `1` means `<list-item>` aligns with the bottom of `<list>`. You can also set `offset` to add a scrolling offset on top of factor.

Example of vertical orientation:

{' '}

Example of horizontal orientation:

### Use `z-index`

## Compatibility



### `<list>`

### `<list-item>`



---
url: /api/elements/built-in/page.md
---

# `<page>`



`<page>` element is the root node, only one `<page>` element is allowed per page. You can omit the explicit `<page>` wrapper, as the frontend framework will generate the root node by default.

## Usage

### Omitting the `<page>` Element

By default, you don't need to manually add the `<page>` element as the frontend framework generates the root node automatically.

In this case, while direct `style` and `class` attributes cannot be set explicitly, you can still style the root node using [`page`](/api/css/selectors.md#using-page-to-select-the-root-node) and [`:root`](/api/css/selectors.md#root-selector) selectors, or select it via [`SelectorQuery:selectRoot()`](/api/lynx-api/selector-query/selector-query-select-root.md).

```css
/* use `page` selector */
page {
  background-color: white;
}

/* or you can use `:root` selector */
:root {
  background-color: white;
}
```

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

### 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/css/properties.md
---




---
url: /api/css/properties/-x-auto-font-size-preset-sizes.md
---

# -x-auto-font-size-preset-sizes

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



## Syntax

```css
-x-auto-font-size: true;
-x-auto-font-size-preset-sizes: 10px 12px 15px;
```

## Formal definition



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




---
url: /api/css/properties/-x-auto-font-size.md
---

# -x-auto-font-size

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



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



## Formal syntax

```
-x-auto-font-size = true (<length>){0,3} | false
```

## Differences from Web

* This is a Lynx-specific property.

## Compatibility




---
url: /api/css/properties/-x-handle-color.md
---

# -x-handle-color

## Introduction

The `-x-handle-color` property specifies the color of the floating marker when copying text, only valid in the selection pseudo-element.

## Examples



## Syntax

```css
::selection {
  -x-handle-color: blue;
}
```

### Values

* [`<color>`](/en/api/css/properties/color.md)
  Sets the color of the floating marker

## Formal definition



## Formal syntax

```
-x-handle-color = <color>
```

## Differences from web

* This is a Lynx-specific property.

## Compatibility




---
url: /api/css/properties/-x-handle-size.md
---

# -x-handle-size

## Introduction

The `-x-handle-size` property specifies the size of the floating marker when copying text, only valid in the selection pseudo-element.

## Examples



## Syntax

```css
::selection {
  -x-handle-size: 5px;
}
```

### Values

* [`<length>`](/api/css/data-type/length.md)
  Sets the size of the floating marker

## Formal definition



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




---
url: /api/css/properties/align-content.md
---

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



## 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`](/en/api/css/properties/max-height.md)/[`max-width`](/en/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



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




---
url: /api/css/properties/align-items.md
---



## Introduction

`align-items` property sets the [`align-self`](/en/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`](/en/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



## 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`&#x20;

Equivalent to `stretch`. Not recommended, as this value doesn't exist in Web.

## Formal definition



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




---
url: /api/css/properties/align-self.md
---



## 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`](/en/api/css/properties/align-items.md).

For flexible box layout, if any child element's cross-axis [`margin`](/en/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



## Syntax

### Values

#### `auto`

**Default value**. Aligns according to the parent's [`align-items`](/en/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



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




---
url: /api/css/properties/animation-delay.md
---



# animation-delay

## Introduction

`animation-delay` property specifies the delay before the animation starts playing.

## Examples

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



## Formal syntax

```css
/* default value: 0s */
animation-delay: <time>;
```

## See Also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation-direction.md
---



# animation-direction

## Introduction

`animation-direction` property specifies whether the animation should play in reverse.

## Examples

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



## Formal syntax

```css
/*default value: normal*/
animation-direction: normal | reverse | alternate | alternate-reverse;
```

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation-duration.md
---



# animation-duration

## Introduction

`animation-duration` property specifies the length of time that an animation should take to complete one cycle.

## Examples

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



## Formal syntax

```css
/* default value: 0s */
animation-duration: <time>;
```

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation-fill-mode.md
---



# animation-fill-mode

## Introduction

`animation-fill-mode` property sets how a CSS animation applies styles to its target before and after its execution.

## Examples

## 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](/en/api/css/properties/animation-direction.md) and [animation-iteration-count](/en/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](/en/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



## Formal syntax

```css
/*none*/
animation-fill-mode: none | forwards | backwards | both;
```

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation-iteration-count.md
---



# animation-iteration-count

## Introduction

`animation-iteration-count` property specifies the number of times an animation should be played.

## Examples

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



## Formal syntax

```css
/*default value: 1*/
animation-iteration-count: <number> | infinite;
```

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation-name.md
---



# animation-name

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

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



## Formal syntax

```
animation-name: <string>;
```

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation-play-state.md
---



# animation-play-state

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

## Syntax

```css
/* Single animation */
animation-play-state: running;
animation-play-state: paused;

/* Multiple animations */
animation-play-state: paused, running, running;
```

## Formal definition



## Formal syntax

```css
/*default value:running*/
animation-play-state: running | paused;
```

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation-timing-function.md
---



# animation-timing-function

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

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



## Formal syntax

```css
/*default value: linear*/
animation-timing-function: linear | ease | ease-in | ease-out | ease-in-out |
  <timing-function>;
```

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/animation.md
---



# animation

## Introduction

The animation property is a shorthand property for [animation-name](/en/api/css/properties/animation-name.md), [animation-duration](/en/api/css/properties/animation-duration.md), [animation-timing-function](/en/api/css/properties/animation-timing-function.md), [animation-delay](/en/api/css/properties/animation-delay.md), [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md), [animation-direction](/en/api/css/properties/animation-direction.md), [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md), and [animation-play-state](/en/api/css/properties/animation-play-state.md).

## Examples

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



## 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](/en/api/lynx-api/event/animation-event.md)

## See also

* [animation](/en/api/css/properties/animation.md)
* [animation-name](/en/api/css/properties/animation-name.md)
* [animation-duration](/en/api/css/properties/animation-duration.md)
* [animation-timing-function](/en/api/css/properties/animation-timing-function.md)
* [animation-delay](/en/api/css/properties/animation-delay.md)
* [animation-iteration-count](/en/api/css/properties/animation-iteration-count.md)
* [animation-direction](/en/api/css/properties/animation-direction.md)
* [animation-fill-mode](/en/api/css/properties/animation-fill-mode.md)
* [animation-play-state](/en/api/css/properties/animation-play-state.md)
* [CSS animation event](/en/api/lynx-api/event/animation-event.md)
* [Animated API](/en/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility




---
url: /api/css/properties/aspect-ratio.md
---

# aspect-ratio

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



## 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`](/en/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



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




---
url: /api/css/properties/background-clip.md
---

## Introduction

The `background-clip` CSS property sets whether an element's background extends underneath its border box, padding box, or content box.

## Examples



## Syntax

```css
background-clip: border-box;
background-clip: padding-box;
background-clip: content-box;

// multiple clip
background-clip: border-box, content-box, padding-box;
```

### Values

* **`border-box`**&#x20;
  The background extends to the outside edge of the border (but underneath the border in z-ordering).

* **`padding-box`**&#x20;
  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.

## Note

If the length of `background-clip` is less than [`background-image`](/en/api/css/properties/background-image.md), the first clip value will effect on all remained [`background-image`](/en/api/css/properties/background-image.md).

## Formal definition



## Formal Syntax

```
<background-clip> = <box>

where

<box> = border-box | padding-box | content-box

```

## Difference between web

* Only support `border-box`、`padding-box`、`content-box`&#x20;

* `background-clip:text` is not support, and if want show text with gradient color, just set `color: <gradient>`.

## Compatibility




---
url: /api/css/properties/background-color.md
---

## Introduction

The `background-color` CSS property sets the background color of an element.

## Examples



## 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)&#x20;
  The uniform color of the background.

* Default value **transparent**&#x20;

## Formal definition



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




---
url: /api/css/properties/background-image.md
---



## Introduction

The `background-image` CSS property sets one or more background images on an element.&#x20;
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.&#x20;
The [border](/en/api/css/properties/border.md) of the element are then drawn on top of them, and the [`background-color`](/en/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`](/en/api/css/properties/background-clip.md) and [`background-origin`](/en/api/css/properties/background-origin.md) CSS properties.&#x20;

## Examples

## 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.&#x20;

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



## Formal Syntax

```
background-image = <bg-image>#

<bg-image> = none | <image>

<image> = <url()> | <gradient>

<url()> = url(<string>)

<gradient> = <linear-gradient()> | <radial-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> )

<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>`
  Only support `linear-gradient` and `radial-gradient`.

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




---
url: /api/css/properties/background-origin.md
---

## Introduction

The `background-origin` CSS property sets the background's origin: from the border start, inside the border, or inside the padding.

## Examples



## 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**&#x20;
  The background is positioned relative to the border box.

* **border-box**&#x20;
  The background is positioned relative to the padding box.

* **content-box**&#x20;
  The background is positioned relative to the content box.

## Formal definition



## Formal Syntax

```
border-box | padding-box | content-box
```

## Difference between web

* Not support `inherit`.

## Compatibility




---
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`](/en/api/css/properties/background-origin.md).

# Examples



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



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




---
url: /api/css/properties/background-repeat.md
---

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



## 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**&#x20;
  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&#x20;
  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&#x20;
  Repeat along x-axis.

* repeat-y&#x20;
  Repeat along y-axis.

* space&#x20;
  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&#x20;
  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



## Formal Syntax

```
<repeat-style> = repeat-x | repeat-y | [ repeat | space | round | no-repeat ]{1,2}
```

## ## Difference between web

* Not support `inherit`

## Compatibility




---
url: /api/css/properties/background-size.md
---

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



## Syntax

```css
background-size: contain;

background-size: 50%;
background-size: 3em;

background-size: auto 1em;
background-size: 50% 25%;
```

### Values

* `cover`&#x20;
  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`](/en/api/css/properties/background-repeat.md) property is set to `no-repeat`.

* `contain`&#x20;
  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**&#x20;
  Scales the background image in the corresponding direction such that its intrinsic proportions are maintained.

* [`<length>`](/api/css/data-type/length.md)&#x20;
  Stretches the image in the corresponding dimension to the specified length. Negative values are not allowed.

* [`<percentage>`](/api/css/data-type/percentage.md)&#x20;
  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`](/en/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`:&#x20;
  The background image is rendered at the specified size.

* `contain` or `cover`:&#x20;
  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:&#x20;
  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



## Formal Syntax

```
<bg-size> = (<length-percentage> | auto){1,2} | cover | contain
```

## Compatibility




---
url: /api/css/properties/background.md
---

## Introduction

The `background` shorthand CSS property sets all background style properties at once, such as [`background-clip`](/en/api/css/properties/background-clip.md),[`background-color`](/en/api/css/properties/background-color.md),[`background-image`](/en/api/css/properties/background-image.md),[`background-origin`](/en/api/css/properties/background-origin.md),[`background-position`](/en/api/css/properties/background-position.md),[`background-repeat`](/en/api/css/properties/background-repeat.md),[`background-size`](/en/api/css/properties/background-size.md).

## Examples



## 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`](/en/api/css/properties/background-origin.md) and [`background-clip`](/en/api/css/properties/background-clip.md). If it is included twice, the first occurrence sets [`background-origin`](/en/api/css/properties/background-origin.md), and the second sets [`background-clip`](/en/api/css/properties/background-clip.md).

> **The [`background-color`](/en/api/css/properties/background-color.md) value may only be included in the last layer specified.**

## Values

#### `<box>`

See [`background-clip`](/en/api/css/properties/background-clip.md) and [`background-origin`](/en/api/css/properties/background-origin.md)

#### `<background-color>`

See [`background-color`](/en/api/css/properties/background-color.md)

#### `<bg-image>`

See [`background-image`](/en/api/css/properties/background-image.md)

#### `<position>`

See [`background-position`](/en/api/css/properties/background-position.md)

#### `<repeat-style>`

See [`background-repeat`](/en/api/css/properties/background-repeat.md)

#### `<bg-size>`

See [`background-size`](/en/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



## 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()>` \_
* `<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




---
url: /api/css/properties/border-bottom-color.md
---

# border-bottom-color

## Introduction

Sets the bottom border color of an element. Used when you need to specify the bottom border color separately.

## Usage Examples



## Syntax

```css
border-bottom-color: red;

border-bottom-color: '#ff0000';
```

### Values

* [`<color>`](/api/css/data-type/color.md)

## Formal Definition



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




---
url: /api/css/properties/border-bottom-left-radius.md
---

# border-bottom-left-radius

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



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



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




---
url: /api/css/properties/border-bottom-right-radius.md
---

# border-bottom-right-radius

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



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



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




---
url: /api/css/properties/border-bottom-style.md
---

# border-bottom-style

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



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



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




---
url: /api/css/properties/border-bottom-width.md
---

# border-bottom-width

## Introduction

Used to set the width of the bottom border.

## Usage Examples



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



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




---
url: /api/css/properties/border-bottom.md
---

# border-bottom

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



## 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>`](/en/api/css/properties/border-bottom.md#formal-definition)

  * See [`<border-bottom-width>`](/en/api/css/properties/border-bottom-width.md)

* [`<line-style>`](/en/api/css/properties/border-bottom.md#formal-definition)

  * See [`<border-bottom-style>`](/en/api/css/properties/border-bottom-style.md)

* [`<color>`](/api/css/data-type/color.md)
  * See [`<border-bottom-color>`](/en/api/css/properties/border-bottom-color.md)

## Formal Definition



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




---
url: /api/css/properties/border-color.md
---

## Introduction

The `border-color` shorthand CSS property sets the color ([`border-top-color`](/en/api/css/properties/border-top-color.md), [`border-right-color`](/en/api/css/properties/border-right-color.md), [`border-bottom-color`](/en/api/css/properties/border-bottom-color.md), [`border-left-color`](/en/api/css/properties/border-left-color.md)) of an element's border.

## Examples



## 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`](/en/api/css/properties/border-top-color.md) and [`border-bottom-color`](/en/api/css/properties/border-bottom-color.md), the second to the [`border-left-color`](/en/api/css/properties/border-left-color.md) and [`border-right-color`](/en/api/css/properties/border-right-color.md).
* When three values are specified, the first color applies to the [`border-top-color`](/en/api/css/properties/border-top-color.md), the second to the [`border-left-color`](/en/api/css/properties/border-left-color.md) and [`border-right-color`](/en/api/css/properties/border-right-color.md), the third to the [`border-bottom-color`](/en/api/css/properties/border-bottom-color.md).
* When four values are specified, the colors apply to the [`border-top-color`](/en/api/css/properties/border-top-color.md), [`border-right-color`](/en/api/css/properties/border-right-color.md), [`border-bottom-color`](/en/api/css/properties/border-bottom-color.md) and [`border-left-color`](/en/api/css/properties/border-left-color.md) in that order (clockwise).

## Formal definition



## Formal syntax

```
<color>{1, 4}
```

## Compatibility




---
url: /api/css/properties/border-end-end-radius.md
---

## 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`](/en/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`](/en/api/css/properties/border-bottom-left-radius.md) property.

## Examples



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



## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-end-end-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-end-end-radius)

## Compatibility




---
url: /api/css/properties/border-end-start-radius.md
---

## 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`](/en/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`](/en/api/css/properties/border-bottom-right-radius.md) property.

## Examples



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



## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]?
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-end-start-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-end-start-radius)

## Compatibility




---
url: /api/css/properties/border-inline-end-color.md
---

## 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`](/en/api/css/properties/border-right-color.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-color`](/en/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



## Formal syntax

```
transparent | <color>
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-inline-end-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-color)

## Compatibility




---
url: /api/css/properties/border-inline-end-style.md
---

## 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`](/en/api/css/properties/border-right-style.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-style`](/en/api/css/properties/border-left-style.md) property.

## Examples



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



## Formal syntax

```
none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-inline-end-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-style)

## Compatibility




---
url: /api/css/properties/border-inline-end-width.md
---

## 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`](/en/api/css/properties/border-right-width.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-width`](/en/api/css/properties/border-left-width.md) property.

## Examples



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



## Formal syntax

```
thin | medium | thick | <length>
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-inline-end-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-width)

## Compatibility




---
url: /api/css/properties/border-inline-start-color.md
---

## 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`](/en/api/css/properties/border-left-color.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-color`](/en/api/css/properties/border-right-color.md) property.

## Examples



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



## Formal syntax

```
transparent | <color>
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-inline-start-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-color)

## Compatibility




---
url: /api/css/properties/border-inline-start-style.md
---

## 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`](/en/api/css/properties/border-left-style.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-style`](/en/api/css/properties/border-right-style.md) property.

## Examples



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



## Formal syntax

```
none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-inline-start-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-style)

## Compatibility




---
url: /api/css/properties/border-inline-start-width.md
---

## 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`](/en/api/css/properties/border-left-width.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-width`](/en/api/css/properties/border-right-width.md) property.

## Examples



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



## Formal syntax

```
thin | medium | thick | <length>
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-inline-start-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-width)

## Compatibility




---
url: /api/css/properties/border-left-color.md
---

## Introduction

Used to set the color of the left border.

## Examples



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



## Formal syntax

```
transparent | <color>
```

## Compatibility




---
url: /api/css/properties/border-left-style.md
---

## Introduction

The **border-left-style** CSS property sets the line style of an element's left [`border`](/en/api/css/properties/border.md).

## Examples



## 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`](/en/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`](/en/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



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




---
url: /api/css/properties/border-left-width.md
---

# border-left-width

## Introduction

Used to set the width of the left border.

## Usage Examples



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



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




---
url: /api/css/properties/border-left.md
---

# border-left

## Introduction

A shorthand property for setting the left border styles of an element. It includes [`border-left-width`](/en/api/css/properties/border-left-width.md), [`border-left-style`](/en/api/css/properties/border-left-style.md), and [`border-left-color`](/en/api/css/properties/border-left-color.md) in order.

## Usage Examples



## Syntax

```css
border-left: 1px solid red;
```

## Values

Can be set in order as follows:

* [`border-left-width`](/en/api/css/properties/border-left-width.md)
  The width of the border.

* [`border-left-style`](/en/api/css/properties/border-left-style.md)
  The style of the border.

* [`border-left-color`](/en/api/css/properties/border-left-color.md)
  The color of the border.

## Formal Definition



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




---
url: /api/css/properties/border-radius.md
---

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



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



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




---
url: /api/css/properties/border-right-color.md
---

## Introduction

Used to set the color of the right border.

## Examples



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



## Formal syntax

```
transparent | <color>
```

## Compatibility




---
url: /api/css/properties/border-right-style.md
---

## Introduction

The **border-right-style** CSS property sets the line style of an element's right [`border`](/en/api/css/properties/border.md).

## Examples



## 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`](/en/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`](/en/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



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




---
url: /api/css/properties/border-right-width.md
---

## Introduction

The border-right-width CSS property sets the width of the left border of an element.

## Examples



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



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




---
url: /api/css/properties/border-right.md
---

## Introduction

The border-right shorthand CSS property sets all the properties of an element's right border.

## Examples



## 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`](/en/api/css/properties/border-right-width.md)
  width of the border

* [`border-right-style`](/en/api/css/properties/border-right-style.md)
  style of the border

* [`border-right-color`](/en/api/css/properties/border-right-color.md)
  color of the border

## Formal definition



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




---
url: /api/css/properties/border-start-end-radius.md
---

## 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`](/en/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`](/en/api/css/properties/border-top-left-radius.md) property.

## Examples



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



## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]?
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-start-end-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-start-end-radius)

## Compatibility




---
url: /api/css/properties/border-start-start-radius.md
---

## 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`](/en/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`](/en/api/css/properties/border-top-right-radius.md) property.

## Examples



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



## Formal syntax

```
[<length> | <percentage>] [[<length> | <percentage>]]?
```

## Extensions

* [direction](/en/api/css/properties/direction.md)
* [mdn:border-start-start-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-start-start-radius)

## Compatibility




---
url: /api/css/properties/border-style.md
---

# border-style

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



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



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




---
url: /api/css/properties/border-top-color.md
---

## Introduction

Used to set the color of the top border.

## Examples



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



## Formal syntax

```
transparent | <color>
```

## Compatibility




---
url: /api/css/properties/border-top-left-radius.md
---

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



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



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




---
url: /api/css/properties/border-top-right-radius.md
---

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



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



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




---
url: /api/css/properties/border-top-style.md
---

## Introduction

The `border-top-style` CSS property sets the line style of an element's top [`border`](/en/api/css/properties/border.md).

## Examples



## 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`](/en/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`](/en/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



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




---
url: /api/css/properties/border-top-width.md
---

## Introduction

The border-top-width CSS property sets the width of the left border of an element.

## Examples



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



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




---
url: /api/css/properties/border-top.md
---

## Introduction

The border-top shorthand CSS property sets all the properties of an element's right border.

## Examples



## 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`](/en/api/css/properties/border-top-width.md)
  width of the border

* [`border-top-style`](/en/api/css/properties/border-top-style.md)
  style of the border

* [`border-top-color`](/en/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



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




---
url: /api/css/properties/border-width.md
---

# border-width

## Introduction

A shorthand property for setting the width of all four borders of an element. It corresponds to [`border-top-width`](/en/api/css/properties/border-top-width.md), [`border-right-width`](/en/api/css/properties/border-right-width.md), [`border-bottom-width`](/en/api/css/properties/border-bottom-width.md), and [`border-left-width`](/en/api/css/properties/border-left-width.md).

## Usage Examples



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



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




---
url: /api/css/properties/border.md
---

## Introduction

The border shorthand CSS property sets an element's border. It sets the values of [border-width](/en/api/css/properties/border-width.md), [border-style](/en/api/css/properties/border-style.md), and [border-color](/en/api/css/properties/border-color.md).

## Examples



## 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`](/en/api/css/properties/border-width.md)
  Sets the thickness of the border.

* [`border-style`](/en/api/css/properties/border-style.md)
  Sets the style of the border.

* [`border-color`](/en/api/css/properties/border-color.md)
  Sets the color of the border.

## Formal definition



{' '}

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




---
url: /api/css/properties/bottom.md
---

## Introduction

The `bottom` CSS property participates in specifying the vertical position. For more information, please refer to property [`position`](/en/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



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



## Formal syntax

```
bottom =
  auto                |
  <length-percentage>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/box-shadow.md
---

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



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




---
url: /api/css/properties/box-sizing.md
---



## 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`](/en/api/css/properties/width.md), [`height`](/en/api/css/properties/height.md), [`min-width`](/en/api/css/properties/min-width.md), [`min-height`](/en/api/css/properties/min-height.md), [`max-width`](/en/api/css/properties/max-width.md), [`max-height`](/en/api/css/properties/max-height.md).

## Examples



## Syntax

```css
box-sizing: border-box;
box-sizing: content-box;
```

### Values

* `border-box`

  **Default value**. The [`width`](/en/api/css/properties/width.md) and [`height`](/en/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`](/en/api/css/properties/width.md) and [`height`](/en/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



## 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`](/en/api/css/properties/flex-basis.md), while Web will.

## Compatibility




---
url: /api/css/properties/clip-path.md
---



# clip-path

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

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

{' '}

### **circle**

{' '}

### **ellipse**

{' '}

### **path**

{' '}

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



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




---
url: /api/css/properties/color.md
---

## Introduction

The `color` CSS property sets the foreground [`color value`](/api/css/data-type/color.md) of an element's text

## Examples



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



## Formal syntax

```
<color> | <gradient>
```

## Compatibility




---
url: /api/css/properties/column-gap.md
---

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



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



## Formal syntax

```
column-gap = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

* `normal` is not supported.

## Compatibility




---
url: /api/css/properties/css-variable.md
---

# Custom properties (`--*`): CSS variables

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



## Syntax

```css
--somekeyword: left;
--somecolor: #0000ff;
```

## 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%;
}
```

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

CSS variables can be referenced anywhere in CSS:

```css
.three {
  /* --main-bg-color: blue; */
  color: white;
  background-color: var(--main-bg-color);
  width: 50%;
  border: 1px blue solid;
}
```

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



---
url: /api/css/properties/direction.md
---



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



## Syntax

```css
direction: normal;
direction: ltr;
direction: rtl;
```

### Values

* `normal`

  **Default value**.

  The [`text-align:start`](/en/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`&#x20;

  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



## Formal syntax

```
direction = normal | ltr | rtl
```

## Difference with the web

* Value `normal`, `lynx-rtl` are introduced to improve page compatibility for `rtl`.

## Compatibility




---
url: /api/css/properties/display.md
---



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



## 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](/en/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`](/en/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



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



## 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`](/en/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
---

## Introduction

The `filter` CSS property applies graphical effects like blur or color shift to an element.

:::info

Currently only the `grayscale` and `blur` functions are supported.

If you use `opacity`, you can directly set properties for the view, [link](/en/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



## Syntax

```css
filter: grayscale(100%);
filter: blur(5px);
```

## Formal definition



## Formal Syntax

```
filter = <filter-function>

<filter-function> =
  <blur()>         |
  <grayscale()>    |


<blur()> =
  blur( <length>? )

<grayscale()> =
  grayscale( [ <percentage> ]? )

```

## Difference between web

Different number of functions supported

## Compatibility




---
url: /api/css/properties/flex-basis.md
---

## 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`](/en/api/css/properties/width.md) or [`height`](/en/api/css/properties/height.md) in case of [`flex-direction: column`](/en/api/css/properties/flex-direction.md) are set for an element, `flex-basis` has priority.

## Examples



## Syntax

```css
/* Specify <'width'> */
flex-basis: 10em;
flex-basis: 3px;
flex-basis: 50%;
flex-basis: auto;
```

### Values

* `auto`

  **Default value**. refer to [`width`](/en/api/css/properties/width.md) and [`height`](/en/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



## Formal syntax

```
flex-basis = auto | <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

* Not under [`box-sizing`](/en/api/css/properties/box-sizing.md) influence.

## Compatibility




---
url: /api/css/properties/flex-direction.md
---

## Introduction

The `flex-direction` CSS property sets how flex items are placed in the flex container defining the main axis and the direction.

## Examples



Note that the values `row` and `row-reverse` are affected by the directionality of the flex container. If its [`dir`](/en/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



## Formal syntax

```
flex-direction =
  row             |
  row-reverse     |
  column          |
  column-reverse
```

## Compatibility




---
url: /api/css/properties/flex-flow.md
---

## Introduction

This property is a shorthand for the CSS properties: [`flex-direction`](/en/api/css/properties/flex-direction.md) and [`flex-wrap`](/en/api/css/properties/flex-wrap.md), specifies the direction of a flex container, as well as its wrapping behavior.

## Examples



## 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`](/en/api/css/properties/flex-direction.md) and [`flex-wrap`](/en/api/css/properties/flex-wrap.md)。

## Formal definition



## Formal syntax

```
flex-flow =
  <'flex-direction'>  ||
  <'flex-wrap'>

<flex-direction> =
  row             |
  row-reverse     |
  column          |
  column-reverse

<flex-wrap> =
  nowrap        |
  wrap          |
  wrap-reverse
```

## Compatibility




---
url: /api/css/properties/flex-grow.md
---

## 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`](/en/api/css/properties/flex-direction.md) value.

`flex-grow` is used alongside the other flex properties [`flex-shrink`](/en/api/css/properties/flex-shrink.md) and [`flex-basis`](/en/api/css/properties/flex-basis.md), and normally defined using the [flex](/en/api/css/properties/flex.md) shorthand to ensure all values are set.

## Examples



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



## Formal syntax

```
flex-grow =
  <number [0,∞]>
```

## Compatibility




---
url: /api/css/properties/flex-shrink.md
---

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



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



## Formal syntax

```
flex-shrink =
  <number [0,∞]>
```

## Compatibility




---
url: /api/css/properties/flex-wrap.md
---

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



## 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`](/en/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`](/en/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



## Formal syntax

```
flex-wrap =
  nowrap        |
  wrap          |
  wrap-reverse
```

## Compatibility




---
url: /api/css/properties/flex.md
---

## 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`](/en/api/css/properties/flex-grow.md), [`flex-shrink`](/en/api/css/properties/flex-shrink.md), [`flex-basis`](/en/api/css/properties/flex-basis.md).

## Examples



## 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>`](/en/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>`](/en/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>`](/en/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>`](/en/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>`](/en/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>`](/en/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>`](/en/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>`](/en/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`](/en/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`](/en/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`](/en/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



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




---
url: /api/css/properties/font-family.md
---

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



## Syntax

```css
font-family: font1, font2;
```

## Formal definition



## Formal syntax

```
font-family =
  [ <string> | <custom-ident> ]#
```

## Compatibility




---
url: /api/css/properties/font-size.md
---

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



## Syntax

```css
/* <length> */
font-size: 12px;
font-size: 0.8em;

/* <percentage> */
font-size: 80%;
```

### Values

* `<length>`&#x20;
  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>`&#x20;
  A positive `<percentage>` value, relative to the parent element's font size.

## Formal definition



## Formal syntax

```
font-size = <length> | <percentage>
```

## Difference with Web

* Only support `<length>` and `<percentage>`

* Default font-size is **14px** not **medium**.

## Compatibility




---
url: /api/css/properties/font-style.md
---

## Introduction

Set the font style.

## Examples



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



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




---
url: /api/css/properties/font-weight.md
---

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



## 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**&#x20;
  Normal font weight. Same as `400`.

* `bold`&#x20;
  Bold font weight. Same as `700`

* `<number>`&#x20;
  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



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




---
url: /api/css/properties/gap.md
---

## 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`](/en/api/css/properties/row-gap.md) and [`column-gap`](/en/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



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



## Formal syntax

```
gap =
  <'row-gap'> <'column-gap'>?

<row-gap> = <length-percentage [0,∞]>

<column-gap> = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/grid-auto-columns.md
---

## 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`](/en/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



## 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`](/en/api/css/properties/min-width.md)/[`min-height`](/en/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`](/en/api/css/properties/align-content.md) and [`justify-content`](/en/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



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




---
url: /api/css/properties/grid-auto-flow.md
---

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



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



## Formal syntax

```
grid-auto-flow = [ row | column ] || dense
```

## Compatibility




---
url: /api/css/properties/grid-auto-rows.md
---

## 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](/en/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



## 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`](/en/api/css/properties/min-width.md)/[`min-height`](/en/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`](/en/api/css/properties/align-content.md) and [`justify-content`](/en/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



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




---
url: /api/css/properties/grid-column-end.md
---

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



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



## Formal syntax

```
grid-column-end = <number> | [span && <number>]
```

## Difference between web

* `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility




---
url: /api/css/properties/grid-column-span.md
---



# &#x20;grid-column-span

:::warning
This API is deprecated.
:::

## Introduction

Contributes a grid span to the grid item's placement.
If there are [`grid-column-start`](/en/api/css/properties/grid-column-start.md) and [`grid-column-end`](/en/api/css/properties/grid-column-end.md), this css property will be overridden.

## Examples



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



## Formal syntax

```
grid-column-span = <number>
```

## Difference between web

* There is no such style in Web.

## Compatibility




---
url: /api/css/properties/grid-column-start.md
---

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



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



## Formal syntax

```
grid-column-start = <number> | [span && <number>]
```

## Difference between web

* `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility




---
url: /api/css/properties/grid-row-end.md
---

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



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



## Formal syntax

```
grid-row-end = <number> | [span && <number>]
```

## Difference between web

* `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility




---
url: /api/css/properties/grid-row-span.md
---



# &#x20;grid-row-span

:::warning
This API is deprecated.
:::

## Introduction

Contributes a grid span to the grid item's placement.
If there are [`grid-row-start`](/en/api/css/properties/grid-row-start.md) and [`grid-row-end`](/en/api/css/properties/grid-row-end.md), this css property will be overridden.

## Examples



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



## Formal syntax

```
grid-row-span = <number>
```

## Difference between web

* There is no such style in Web.

## Compatibility




---
url: /api/css/properties/grid-row-start.md
---

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



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



## Formal syntax

```
grid-row-start = <number> | [span && <number>]
```

## Difference between web

* `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility




---
url: /api/css/properties/grid-template-columns.md
---

## Introduction

The `grid-template-columns` CSS property defines track sizing functions of the grid columns.

## Examples



## 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`](/en/api/css/properties/min-width.md)/[`min-height`](/en/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`](/en/api/css/properties/align-content.md) and [`justify-content`](/en/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



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




---
url: /api/css/properties/grid-template-rows.md
---

## Introduction

The `grid-template-rows` CSS property defines track sizing functions of the grid rows.

## Examples



## 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`](/en/api/css/properties/min-width.md)/[`min-height`](/en/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`](/en/api/css/properties/align-content.md) and [`justify-content`](/en/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



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




---
url: /api/css/properties/height.md
---

## 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`](/en/api/css/properties/box-sizing.md) is set to `content-box`, however, it instead determines the height of the content area.

The [`min-height`](/en/api/css/properties/min-height.md) and [`max-height`](/en/api/css/properties/max-height.md) properties override `height`.

## Examples



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



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




---
url: /api/css/properties/image-rendering.md
---

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



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



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




---
url: /api/css/properties/inset-inline-end.md
---

## 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`](/en/api/css/properties/right.md) or [`left`](/en/api/css/properties/left.md) property depending on the values defined for [`direction`](/en/api/css/properties/direction.md).

In `LTR`, it corresponds to the [`right`](/en/api/css/properties/right.md) property.
In `RTL`, it corresponds to the [`left`](/en/api/css/properties/left.md) property.

## Examples



## 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`](/en/api/css/properties/left.md) property.

## Formal definition



## Formal syntax

takes the same as the [`left`](/en/api/css/properties/left.md) property.

## Difference with the web

* In Lynx, `writing-mode` is not supported.

## Compatibility




---
url: /api/css/properties/inset-inline-start.md
---

## 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`](/en/api/css/properties/right.md) or [`left`](/en/api/css/properties/left.md) property depstarting on the values defined for [`direction`](/en/api/css/properties/direction.md).

In `LTR`, it corresponds to the [`left`](/en/api/css/properties/left.md) property.
In `RTL`, it corresponds to the [`right`](/en/api/css/properties/right.md) property.

## Examples



## 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`](/en/api/css/properties/left.md) property.

## Formal definition



## Formal syntax

takes the same as the [`left`](/en/api/css/properties/left.md) property.

## Difference with the web

* In Lynx, `writing-mode` is not supported.

## Compatibility




---
url: /api/css/properties/justify-content.md
---

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



## 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`](/en/api/css/properties/max-height.md)/[`max-width`](/en/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`](/en/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



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




---
url: /api/css/properties/justify-items.md
---

## Introduction

The CSS `justify-items` property defines the default [`justify-self`](/en/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



## 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`](/en/api/css/properties/max-height.md)/[`max-width`](/en/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



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




---
url: /api/css/properties/justify-self.md
---

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



## 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`](/en/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`](/en/api/css/properties/max-height.md)/[`max-width`](/en/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



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




---
url: /api/css/properties/left.md
---

## Introduction

The `left` CSS property participates in specifying the horizontal position of a positioned element. For more information, please refer to property [`position`](/en/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



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



## Formal syntax

```
left =
  auto                 |
  <length-percentage>  |

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/letter-spacing.md
---

## Introduction

The `letter-spacing` CSS property sets the horizontal spacing behavior between text characters.

## Examples



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



## Formal syntax

```
<length>
```

## Difference with Web

* Only support `<length>`.

## Compatibility




---
url: /api/css/properties/line-height.md
---

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



### Values

* normal&#x20;
  Default value.

* `<number>`&#x20;
  The used value is this unitless `<number>` multiplied by the element's own font size.

* `<length>`&#x20;
  The specified `<length>` is used in the calculation of the line box height.

## Formal definition



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




---
url: /api/css/properties/linear-cross-gravity.md
---



# &#x20;linear-cross-gravity

:::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`](/en/api/css/properties/align-items.md) in [flexible box layout](/guide/ui/layout/flexible-box-layout.md).

When using [`linear-layout-gravity`](/en/api/css/properties/linear-layout-gravity.md), [`align-self`](/en/api/css/properties/align-self.md), [`linear-cross-gravity`](/en/api/css/properties/linear-cross-gravity.md), and [`align-items`](/en/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



## 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`](/en/api/css/properties/width.md) when [`linear-direction: column`](/en/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



## Formal syntax

```
linear-cross-gravity = none | start | end | center | stretch
```

## Difference between web

* No such style in Web.

## Compatibility




---
url: /api/css/properties/linear-direction.md
---



## 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`](/en/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.

:::info
`linear-orientation` is deprecated, will be removed in the future.
:::

## Examples



## 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`&#x20;

  Equivalent to `column`.

* `horizontal`&#x20;

  Equivalent to `row`.

* `horizontal-reverse`&#x20;

  Equivalent to `row-reverse`.

* `vertical-reverse`&#x20;

  Equivalent to `column-reverse`.

## Formal definition



## Formal syntax

```
linear-direction = column | row | column-reverse | row-reverse
```

## Difference between web

* No such style in Web.

## Compatibility




---
url: /api/css/properties/linear-gravity.md
---



# &#x20;linear-gravity

:::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`](/en/api/css/properties/justify-content.md).

:::info
When using `justify-content` and `linear-gravity` both, `linear-gravity` will override `justify-content`.
:::

## Examples



## 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`&#x20;

  Not recommended, it is recommended to use `start`. Align up, vertical layout takes effect.

* `bottom`&#x20;

  Not recommended, it is recommended to use `end`. Align down, vertical layout takes effect.

* `left`&#x20;

  Not recommended, it is recommended to use `start`. Align left, horizontal layout takes effect.

* `right`&#x20;

  Not recommended, it is recommended to use `end`. Align right, horizontal layout takes effect.

* `center-vertical`&#x20;

  Not recommended, it is recommended to use `center`. Centered vertically, vertical layout takes effect.

* `center-horizontal`&#x20;

  Not recommended, it is recommended to use `center`. Centered horizontally, horizontal layout takes effect.

## Formal definition



## Formal syntax

```
linear-gravity = none | start | end | center | space-between
```

## Difference between web

* No such style in Web.

## Compatibility




---
url: /api/css/properties/linear-layout-gravity.md
---



# &#x20;linear-layout-gravity

:::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`](/en/api/css/properties/align-self.md) in flexible box layout.

When using [`linear-layout-gravity`](/en/api/css/properties/linear-layout-gravity.md), [`align-self`](/en/api/css/properties/align-self.md), [`linear-cross-gravity`](/en/api/css/properties/linear-cross-gravity.md), and [`align-items`](/en/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



## 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`](/en/api/css/properties/width.md) when [`linear-direction: column`](/en/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`&#x20;

  Align the top of the parent element, the horizontal layout takes effect.

* `bottom`&#x20;

  Align the bottom of the parent element, the horizontal layout takes effect.

* `left`&#x20;

  Align the left side of the parent element, vertical layout takes effect.

* `right`&#x20;

  Align the right side of the parent element, vertical layout takes effect.

* `center-vertical`&#x20;

  Centered in the vertical direction, the horizontal layout of the parent element takes effect.

* `center-horizontal`&#x20;

  Centered in the horizontal direction, the vertical layout of the parent element takes effect.

* `fill-vertical`&#x20;

  Fill the entire container vertically, and the horizontal layout of the parent element takes effect.

* `fill-horizontal`&#x20;

  Fill up the container horizontally, and the vertical layout of the parent element takes effect.

## Formal definition



## Formal syntax

```
linear-layout-gravity = none | stretch | start | end | center
```

## Difference between web

* No such style in Web.

## Compatibility



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



# &#x20;linear-weight-sum

:::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`](/en/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.



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



## Formal syntax

```
linear-weight-sum = <number>
```

## Difference between web

* No such style in Web.

## Compatibility



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

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



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



## Formal syntax

```
linear-weight = <number>
```

## Difference between web

* No such style in Web.

## Compatibility



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

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



## 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`](/en/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



## 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`](/en/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




---
url: /api/css/properties/margin-inline-end.md
---

## 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`](/en/api/css/properties/margin-right.md) property.
In `RTL` direction, it corresponds to the [`margin-left`](/en/api/css/properties/margin-left.md) property.

## Examples



## 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`](/en/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



## 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`](/en/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




---
url: /api/css/properties/margin-inline-start.md
---

## 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`](/en/api/css/properties/margin-left.md) property.
In `RTL` direction, it corresponds to the [`margin-right`](/en/api/css/properties/margin-right.md) property.

## Examples



## 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`](/en/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



## 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`](/en/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




---
url: /api/css/properties/margin-left.md
---

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



## 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`](/en/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



## 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`](/en/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




---
url: /api/css/properties/margin-right.md
---

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



## 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`](/en/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



## 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`](/en/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




---
url: /api/css/properties/margin-top.md
---

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



## 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`](/en/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



## 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`](/en/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




---
url: /api/css/properties/margin.md
---

## 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](/en/api/css/properties/margin-top.md), [margin-right](/en/api/css/properties/margin-right.md), [margin-bottom](/en/api/css/properties/margin-bottom.md), [margin-left](/en/api/css/properties/margin-left.md).

## Examples



## 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`](/en/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



## 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`](/en/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




---
url: /api/css/properties/mask-image.md
---

## Introduction

The mask-image CSS property sets the image that is used as mask layer for an element.
By default this means the alpha channel of the mask image will be multiplied with the alpha channel of the element.

## Syntax

```css
/* Keyword value */
mask-image: none;

/* <image> values */
mask-image: linear-gradient(rgba(0, 0, 0, 1), transparent);
mask-image: url(mask.png);

/* Multiple values */
mask-image: url(mask.png), linear-gradient(rgba(0, 0, 0, 1), transparent);
```

### Values

#### `none`

This keyword is interpreted as an opaque white image layer.

#### `<image>`

An image value used as mask image layer.

### Formal Definition



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




---
url: /api/css/properties/mask.md
---

## 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](/en/api/css/properties/mask-image.md).

#### `<position>`

Sets the position of the mask image. See [mask-position]().

#### `<bg-size>`

Sets the size of the mask image. See [mask-size]().

#### `<repeat-style>`

Sets the repetition of the mask image. See [mask-repeat]().

#### `<geometry-box>`

If only one `<geometry-box` value is given, it sets both [mask-origin]() and [mask-clip](). If two `<geometry-box>` values are present, then the first sets mask-origin and the second sets [mask-clip]().

#### `<geometry-box> | no-clip`

Sets the area that is affected by the mask image. See [mask-clip]().

## Formal definition

|                              |                                                                                                                                                                                                                                                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Initial values**           | as each of the properties of the shorthand:    [mask-image](/en/api/css/properties/mask-image.md): none mask-repeat: repeatmask-position: centermask-clip: border-boxmask-origin: border-boxmask-size: auto |
| **Applies to**               | Views only. It may work on some other elements, but it is recommended that only use it on \<view>                                                                                                                                                                                              |
| **Inherited**                | No                                                                                                                                                                                                                                                                                                               |
| **Percentages**              | as each of the properties of the shorthand:   mask-position: refer to size of mask painting area minus size of mask layer image (see the text for background-position)                                                             |
| **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




---
url: /api/css/properties/max-height.md
---

## Introduction

To specify max height of a view. It prevents the applied value of [`height`](/en/api/css/properties/height.md) becoming larger than the specified value of `max-height`.
The priority of `max-height` is higher than [`height`](/en/api/css/properties/height.md) and [`min-height`](/en/api/css/properties/min-height.md).

## Examples



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



## 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`](/en/api/css/properties/min-height.md), [`min-height`](/en/api/css/properties/min-height.md) will be ignored.
3. `none`, `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility




---
url: /api/css/properties/max-width.md
---

## Introduction

To specify max width of a view. It prevents the applied value of [`width`](/en/api/css/properties/width.md) becoming larger than the specified value of `max-width`.
The priority of `max-width` is higher than [`width`](/en/api/css/properties/width.md) and [`min-width`](/en/api/css/properties/min-width.md).

## Examples



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



## 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`](/en/api/css/properties/min-width.md), [`min-width`](/en/api/css/properties/min-width.md) will be ignored.
3. `none`, `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility




---
url: /api/css/properties/min-height.md
---

## Introduction

To specify min height of a view. It prevents the applied value of [`height`](/en/api/css/properties/height.md) becoming larger than the specified value of `min-height`.
The priority of `min-height` is higher than [`height`](/en/api/css/properties/height.md) but lower than [`max-height`](/en/api/css/properties/max-height.md).

## Examples



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



## 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 `min-height` is specified smaller than [`min-height`](/en/api/css/properties/min-height.md), [`min-height`](/en/api/css/properties/min-height.md) 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




---
url: /api/css/properties/min-width.md
---

## Introduction

To specify min width of a view. It prevents the applied value of [`width`](/en/api/css/properties/width.md) becoming larger than the specified value of `min-width`.
The priority of `min-width` is higher than [`width`](/en/api/css/properties/width.md) but lower than [`max-width`](/en/api/css/properties/max-width.md).

## Examples



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



## 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 `min-width` is specified smaller than [`min-width`](/en/api/css/properties/min-width.md), [`min-width`](/en/api/css/properties/min-width.md) 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




---
url: /api/css/properties/opacity.md
---

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



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



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




---
url: /api/css/properties/order.md
---

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



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



## Difference with the Web

1. It is not supported to use on [`position: absolute/fixed/sticky`](/en/api/css/properties/position.md) flex and grid container children.
2. Using `order` will not influence the element's painting order in Lynx.

## Compatibility




---
url: /api/css/properties/overflow-x.md
---

## Introduction

The overflow-x property specifies whether to clip the content when it overflows at the left and right edges.

## Examples



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



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




---
url: /api/css/properties/overflow-y.md
---

## Introduction

The overflow-y property specifies whether to clip the content when it overflows at the top and bottom edges.

## Examples



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



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




---
url: /api/css/properties/overflow.md
---

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



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



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




---
url: /api/css/properties/padding-bottom.md
---

## Introduction

Sets the height of the padding area on the bottom of an element. Negative values are not allowed for padding.

## Examples



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



## Formal syntax

```
padding-bottom =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/padding-inline-end.md
---

## Introduction

Defines the logical inline end padding of an element, which maps to a physical padding depending on the element's [`direction`](/en/api/css/properties/direction.md). Must be nonnegative.

In `LTR` mode, `padding-inline-end` taking the same values as the [`padding-right`](/en/api/css/properties/padding-right.md).
In `RTL` mode, `padding-inline-end` taking the same values as the [`padding-left`](/en/api/css/properties/padding-left.md).

## Examples



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



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




---
url: /api/css/properties/padding-inline-start.md
---

## Introduction

Defines the logical inline start padding of an element, which maps to a physical padding depending on the element's [`direction`](/en/api/css/properties/direction.md). Must be nonnegative.

In `LTR` mode, `padding-inline-start` taking the same values as the [`padding-left`](/en/api/css/properties/padding-left.md).
In `RTL` mode, `padding-inline-start` taking the same values as the [`padding-right`](/en/api/css/properties/padding-right.md).

## Examples



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



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




---
url: /api/css/properties/padding-left.md
---

## Introduction

Sets the width of the padding area on the left of an element. Negative values are not allowed for padding.

## Examples



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



## Formal syntax

```
padding-left =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

## Compatibility




---
url: /api/css/properties/padding-right.md
---

## Introduction

Sets the width of the padding area on the right of an element. Negative values are not allowed for padding.

## Examples



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



## Formal syntax

```
padding-right =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/padding-top.md
---

## Introduction

Sets the height of the padding area on the top of an element. Negative values are not allowed for padding.

## Examples



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



## Formal syntax

```
padding-top =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/padding.md
---

## 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`](/en/api/css/properties/padding-top.md), [`padding-right`](/en/api/css/properties/padding-right.md)、[`padding-bottom`](/en/api/css/properties/padding-bottom.md), [`padding-left`](/en/api/css/properties/padding-left.md).

## Examples



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



## Formal syntax

```
padding =
  <'padding-top'>{1,4}

<padding-top> =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/perspective.md
---

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



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



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




---
url: /api/css/properties/position.md
---

## Introduction

The `position` CSS property sets how an element is positioned in a document. The [`top`](/en/api/css/properties/top.md), [`right`](/en/api/css/properties/right.md), [`bottom`](/en/api/css/properties/bottom.md), and [`left`](/en/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`](/en/api/css/properties/top.md) and [`bottom`](/en/api/css/properties/bottom.md) properties specify the vertical offset from its normal position; the [`left`](/en/api/css/properties/left.md) and [`right`](/en/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`](/en/api/css/properties/height.md) and [`width`](/en/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



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



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



## FAQ

1. If using [`z-index`](/en/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
---

## 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`](/en/api/css/properties/relative-id.md).

## Examples



## 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`](/en/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-align-bottom = none | parent | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-align-inline-end.md
---

## Introduction

Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to [`id`](/en/api/css/properties/relative-id.md).

When [`direction`](/en/api/css/properties/direction.md) is `ltr`, `relative-align-inline-end` is equivalent to [`relative-align-right`](/en/api/css/properties/relative-align-right.md);

When [`direction`](/en/api/css/properties/direction.md) is `rtl/lynx-rtl`,`relative-align-inline-end` is equivalent to [`relative-align-left`](/en/api/css/properties/relative-align-left.md);

## Examples



## 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`](/en/api/css/properties/relative-align-left.md) property.

## Formal definition



## Formal syntax

```
relative-align-inline-end = none | parent | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-align-inline-start.md
---

## Introduction

Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to [`id`](/en/api/css/properties/relative-id.md).

When [`direction`](/en/api/css/properties/direction.md) is `ltr`, `relative-align-inline-start` is equivalent to [`relative-align-left`](/en/api/css/properties/relative-align-left.md);

When [`direction`](/en/api/css/properties/direction.md) is `rtl/lynx-rtl`,`relative-align-inline-start` is equivalent to [`relative-align-right`](/en/api/css/properties/relative-align-right.md);

## Examples



## 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`](/en/api/css/properties/relative-align-left.md) property.

## Formal definition



## Formal syntax

```
relative-align-inline-start = none | parent | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-align-left.md
---

## 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`](/en/api/css/properties/relative-id.md).

## Examples



## 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`](/en/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-align-left = none | parent | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-align-right.md
---

## 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`](/en/api/css/properties/relative-id.md).

## Examples



## 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`](/en/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-align-right = none | parent | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-align-top.md
---

## 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`](/en/api/css/properties/relative-id.md).

## Examples



## 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`](/en/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-align-top = none | parent | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-bottom-of.md
---

## Introduction

The current element is to the below of the sibling element specified corresponding to [`id`](/en/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/en/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-bottom-of = none | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-center.md
---

## Introduction

Used to set the centering alignment of the current element in the [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples



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



## Formal syntax

```
relative-center = none | both | vertical | horizontal
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-id.md
---

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



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



## Formal syntax

```
relative-id = <integer [1,∞]>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-inline-end-of.md
---

## Introduction

The current element is to the left/right of the sibling element corresponding to the specified [`id`](/en/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

When [`direction`](/en/api/css/properties/direction.md) is `ltr`, `relative-inline-end-of` is equivalent to [`relative-right-of`](/en/api/css/properties/relative-right-of.md);

When [`direction`](/en/api/css/properties/direction.md) is `rtl/lynx-rtl`, `relative-inline-end-of` is equivalent to [`relative-left-of`](/en/api/css/properties/relative-left-of.md).

## Examples



## Values

The `relative-inline-end-of` property takes the same values as the [`relative-left-of`](/en/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



## Formal syntax

```
relative-inline-end-of = none | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-inline-start-of.md
---

## Introduction

The current element is to the left/right of the sibling element corresponding to the specified [`id`](/en/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

When [`direction`](/en/api/css/properties/direction.md) is `ltr`, `relative-inline-start-of` is equivalent to [`relative-left-of`](/en/api/css/properties/relative-left-of.md);

When [`direction`](/en/api/css/properties/direction.md) is `rtl/lynx-rtl`, `relative-inline-start-of` is equivalent to [`relative-right-of`](/en/api/css/properties/relative-right-of.md).

## Examples



## Values

The `relative-inline-start-of` property takes the same values as the [`relative-left-of`](/en/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



## Formal syntax

```
relative-inline-start-of = none | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-layout-once.md
---

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



## Formal syntax

```
relative-layout-once = true | false
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-left-of.md
---

## Introduction

The current element is to the left of the sibling element specified corresponding to [`id`](/en/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/en/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-left-of = none | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-right-of.md
---

## Introduction

The current element is to the right of the sibling element specified corresponding to [`id`](/en/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/en/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-right-of = none | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/relative-top-of.md
---

## Introduction

The current element is to the top of the sibling element specified corresponding to [`id`](/en/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/en/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/en/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



## Formal syntax

```
relative-top-of = none | <number>
```

## Difference between web

* There is no such style in web.

## Compatibility




---
url: /api/css/properties/right.md
---

## Introduction

The `right` CSS property participates in specifying the horizontal position of a positioned element. For more information, please refer to property [`position`](/en/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



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



## Formal syntax

```
right =
  auto                 |
  <length-percentage>  |

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility




---
url: /api/css/properties/row-gap.md
---

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



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



## Difference with the web

[mdn: row-gap](https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap)

1. `normal` is not supported.

## Compatibility



## FAQ



---
url: /api/css/properties/text-align.md
---

## Introduction

The `text-align` CSS property sets the horizontal alignment of the inline-level content inside a block element.

## Examples

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



## Formal syntax

```
left | right | center | start | end
```

## Difference with web

* Not support `justify-all` and `justify`.

* Not support `match-parent`.

## Compatibility




---
url: /api/css/properties/text-decoration.md
---

## Introduction

The `text-decoration` shorthand CSS property sets the appearance of decorative lines on text.

## Examples



## 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`&#x20;
  **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



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




---
url: /api/css/properties/text-indent.md
---

## Introduction

The text-indent attribute can define the indentation before the first line of text content of a text.

## Examples



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



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




---
url: /api/css/properties/text-overflow.md
---

## Introduction

The `text-overflow` CSS property sets how hidden overflow content is signaled to users.

## Examples



## Syntax

```css
text-overflow: clip;
text-overflow: ellipsis;
```

### Values

* `clip`&#x20;
  **Default Value**。This keyword value will truncate the text at the limit of the content area.

* `ellipsis`&#x20;
  This keyword value will display an ellipsis (`…`, `U+2026 HORIZONTAL ELLIPSIS`) to represent clipped text.

## Formal definition



## Formal syntax

```
clip | ellipsis
```

## Difference between web

* Not support `fade` 。

* Not support `<string>` with custom clip text.

## Compatibility




---
url: /api/css/properties/text-shadow.md
---

## Introduction

The `text-shadow` CSS property adds shadows to text.

## Examples



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



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




---
url: /api/css/properties/text-stroke-color.md
---

## Introduction

`text-stroke-color` specifies the stroke color of characters of text.

## Example



## Syntax

```css
text-stroke-color: red;
text-stroke-color: #e08ab4;
text-stroke-color: rgb(200, 100, 0);
```

### Values

* [`<color>`](/en/api/css/properties/color.md)
  The color of the stroke.

## Formal definition



## Formal syntax

```css
text-stroke-color = <color>
```

## Compatibility




---
url: /api/css/properties/text-stroke-width.md
---

## Introduction

The `text-stroke-width` property specifies the width of the text stroke.



## Examples

## Syntax

```css
text-stroke-width: 2px;
text-stroke-width: 0.1em;
text-stroke-width: 5pt;
```

### Values

* [`<length>`](/api/css/data-type/length.md)
  The width of the stroke.

## Formal definition



## Formal syntax

```css
text-stroke-width = <length[0,∞]>
```

## Differences from Web

* Does not support setting attribute values such as `thin`.

## Compatibility




---
url: /api/css/properties/text-stroke.md
---

## Introduction

The `text-stroke` CSS property specifies the width and color of strokes for text characters.

## Examples



## Syntax

```css
text-stroke: 4px green;
```

### Values

* none&#x20;
  **Default value**

* [`<length>`](/api/css/data-type/length.md)&#x20;
  Set the width of the stroke

* [`<color>`](/en/api/css/properties/color.md)&#x20;
  Set the color of the stroke

## Formal definition



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




---
url: /api/css/properties/top.md
---

## Introduction

The `top` CSS property participates in specifying the vertical position. For more information, please refer to property [`position`](/en/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



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



## Difference with the web

[mdn: top](https://developer.mozilla.org/en-US/docs/Web/CSS/bottom)

## Compatibility



## FAQ



---
url: /api/css/properties/transform-origin.md
---

## Introduction

The transform-origin CSS property sets the origin for an element's transformations.

## Examples



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



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




---
url: /api/css/properties/transform.md
---

## Introduction

The transform CSS property lets you rotate, scale, skew, or translate an element.

## Examples



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

```
scale( [ <angle> | <zero> ], [ <angle> | <zero> ] )
```

* **skewX**

```
scaleX( [ <angle> | <zero> ] )
```

* **skewY**

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



## Note

:::info

* If you want 3D effect when transform rotateX and rotateY rotate, you need to cooperate with [perspective property](/en/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




---
url: /api/css/properties/transition-delay.md
---



# transition-delay

## Introduction

The transition-delay CSS property specifies the duration to wait before starting a property's transition effect when its value changes.

## Examples

## Syntax

```css
transition-delay: 2s;
transition-delay: 300ms;
```

### Values

* [`<time>`](/api/css/data-type/time.md)

* Default Value
  **0s**

## Formal definition



## Formal syntax

```
transition-delay:`<time>`;
```

## More

* [transition-property](/en/api/css/properties/transition-property.md)
* [transition-duration](/en/api/css/properties/transition-duration.md)
* [transition](/en/api/css/properties/transition.md)
* [transition-timing-function](/en/api/css/properties/transition-timing-function.md)
* [Animation Event](/en/api/lynx-api/event/animation-event.md)

## Note

:::info

* `duration` and `delay` require **units**, and it is strongly recommended to bring units.

:::

## Compatibility




---
url: /api/css/properties/transition-duration.md
---



# transition-duration

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

## 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](/en/api/css/properties/transition-property.md)
* [transition-delay](/en/api/css/properties/transition-delay.md)
* [transition](/en/api/css/properties/transition.md)
* [transition-timing-function](/en/api/css/properties/transition-timing-function.md)
* [Animation Event](/en/api/lynx-api/event/animation-event.md)

## Note

:::info

* `duration` and `delay` require **units**, and it is strongly recommended to bring units.

:::

## Compatibility




---
url: /api/css/properties/transition-property.md
---



# transition-property

## Introduction

The transition-property CSS property sets the CSS properties to which a transition effect should be applied.

## Examples

## 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;
transition-property:;
```

### Values

* left
* right
* top
* bottom
* width
* height
* opacity
* background-color
* color
* transform
* 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



## Formal syntax

```
transition-property:opacity|width|height|background-color|visibility|top|right|left|bottom|transform|all|none;
```

## More

* [transition-delay](/en/api/css/properties/transition-delay.md)
* [transition-duration](/en/api/css/properties/transition-duration.md)
* [transition](/en/api/css/properties/transition.md)
* [transition-timing-function](/en/api/css/properties/transition-timing-function.md)
* [Animation Event](/en/api/lynx-api/event/animation-event.md)

## Compatibility




---
url: /api/css/properties/transition-timing-function.md
---



# transition-timing-function

## Introduction

The transition-timing-function CSS property sets how intermediate values are calculated for CSS properties being affected by a transition effect.

## Examples

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



## Formal syntax

```
transition-timing-function:linear|ease|ease-in|ease-out|ease-in-out|square-bezier()|cubic-bezier();
```

## More

* [transition-delay](/en/api/css/properties/transition-delay.md)
* [transition-duration](/en/api/css/properties/transition-duration.md)
* [transition](/en/api/css/properties/transition.md)
* [transition-timing-function](/en/api/css/properties/transition-timing-function.md)
* [Animation Event](/en/api/lynx-api/event/animation-event.md)

## Compatibility




---
url: /api/css/properties/transition.md
---



# transition

## Introduction

The transition CSS property is a shorthand property for `transition-property`, `transition-duration`, `transition-timing-function`, and `transition-delay`.

## Example

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



## Formal syntax

```css
transition: <transition-property> || <transition-duration> ||
  <transition-timing-function> || <transition-delay>;
```

## Transition Event

* [Transition Event](/en/api/lynx-api/event/animation-event.md)

## More

* [transition-property](/en/api/css/properties/transition-property.md)
* [transition-duration](/en/api/css/properties/transition-duration.md)
* [transition-delay](/en/api/css/properties/transition-delay.md)
* [transition-timing-function](/en/api/css/properties/transition-timing-function.md)
* [Animation Event](/en/api/lynx-api/event/animation-event.md)

## Compatibility




---
url: /api/css/properties/vertical-align.md
---

## Introduction

The vertical-align property sets vertical alignment of inline element.

## Examples



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



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




---
url: /api/css/properties/visibility.md
---

## Introduction

The visibility CSS property shows or hides an element without changing the layout of a document.

## Examples



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



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




---
url: /api/css/properties/white-space.md
---

## Introduction

`white-space`CSS property sets how white space inside an element is handled.。

## Examples



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



## Formal syntax

```
normal | nowrap
```

## Difference with Web

* Only support `normal` and `nowrap`

## Compatibility




---
url: /api/css/properties/width.md
---

## 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`](/en/api/css/properties/box-sizing.md) is set to `content-box`, however, it instead determines the width of the content area.

The [`min-width`](/en/api/css/properties/min-width.md) and [`max-width`](/en/api/css/properties/max-width.md) properties override `width`.

## Examples



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



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




---
url: /api/css/properties/word-break.md
---

## Introduction

Used to specify how to break lines within a word.

## Examples



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



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




---
url: /api/css/properties/z-index.md
---

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



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



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




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

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



## Difference from W3C

Not support font-style,font-weight and font-variant.

## Compatibility




---
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`, `max-width`, `min-width`, `max-height`, `min-height`, `padding-left`, `padding-right`, `padding-top`, `padding-bottom`, `margin-left`, `margin-right`, `margin-top`, `margin-bottom`, `border-left-width`, `border-right-width`, `border-top-width`, `border-bottom-width`, `border-left-color`, `border-right-color`, `border-top-color`, `border-bottom-color`, `flex-basis`, `flex-grow`, `filter`.



---
url: /api/css/data-type.md
---


# Data Type

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

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




---
url: /api/css/data-type/color.md
---

# `<color>`

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)       | transparent |
| aliceblue            | rgba(240, 248, 255, 1) |    |
| antiquewhite         | rgba(250, 235, 215, 1) |    |
| aqua                 | rgba(0, 255, 255, 1)   |      |
| aquamarine           | rgba(127, 255, 212, 1) |    |
| azure                | rgba(240, 255, 255, 1) |    |
| beige                | rgba(245, 245, 220, 1) |    |
| bisque               | rgba(255, 228, 196, 1) |    |
| black                | rgba(0, 0, 0, 1)       |          |
| blanchedalmond       | rgba(255, 235, 205, 1) |    |
| blue                 | rgba(0, 0, 255, 1)     |        |
| blueviolet           | rgba(138, 43, 226, 1)  |     |
| brown                | rgba(165, 42, 42, 1)   |      |
| burlywood            | rgba(222, 184, 135, 1) |    |
| cadetblue            | rgba(95, 158, 160, 1)  |     |
| chartreuse           | rgba(127, 255, 0, 1)   |      |
| chocolate            | rgba(210, 105, 30, 1)  |     |
| coral                | rgba(255, 127, 80, 1)  |     |
| cornflowerblue       | rgba(100, 149, 237, 1) |    |
| cornsilk             | rgba(255, 248, 220, 1) |    |
| crimson              | rgba(220, 20, 60, 1)   |      |
| cyan                 | rgba(0, 255, 255, 1)   |      |
| darkblue             | rgba(0, 0, 139, 1)     |        |
| darkcyan             | rgba(0, 139, 139, 1)   |      |
| darkgoldenrod        | rgba(184, 134, 11, 1)  |     |
| darkgray             | rgba(169, 169, 169, 1) |    |
| darkgreen            | rgba(0, 100, 0, 1)     |        |
| darkgrey             | rgba(169, 169, 169, 1) |    |
| darkkhaki            | rgba(189, 183, 107, 1) |    |
| darkmagenta          | rgba(139, 0, 139, 1)   |      |
| darkolivegreen       | rgba(85, 107, 47, 1)   |      |
| darkorange           | rgba(255, 140, 0, 1)   |      |
| darkorchid           | rgba(153, 50, 204, 1)  |     |
| darkred              | rgba(139, 0, 0, 1)     |        |
| darksalmon           | rgba(233, 150, 122, 1) |    |
| darkseagreen         | rgba(143, 188, 143, 1) |    |
| darkslateblue        | rgba(72, 61, 139, 1)   |      |
| darkslategray        | rgba(47, 79, 79, 1)    |       |
| darkslategrey        | rgba(47, 79, 79, 1)    |       |
| darkturquoise        | rgba(0, 206, 209, 1)   |      |
| darkviolet           | rgba(148, 0, 211, 1)   |      |
| deeppink             | rgba(255, 20, 147, 1)  |     |
| deepskyblue          | rgba(0, 191, 255, 1)   |      |
| dimgray              | rgba(105, 105, 105, 1) |    |
| dimgrey              | rgba(105, 105, 105, 1) |    |
| dodgerblue           | rgba(30, 144, 255, 1)  |     |
| firebrick            | rgba(178, 34, 34, 1)   |      |
| floralwhite          | rgba(255, 250, 240, 1) |    |
| forestgreen          | rgba(34, 139, 34, 1)   |      |
| fuchsia              | rgba(255, 0, 255, 1)   |      |
| gainsboro            | rgba(220, 220, 220, 1) |    |
| ghostwhite           | rgba(248, 248, 255, 1) |    |
| gold                 | rgba(255, 215, 0, 1)   |      |
| goldenrod            | rgba(218, 165, 32, 1)  |     |
| gray                 | rgba(128, 128, 128, 1) |    |
| green                | rgba(0, 128, 0, 1)     |        |
| greenyellow          | rgba(173, 255, 47, 1)  |     |
| grey                 | rgba(128, 128, 128, 1) |    |
| honeydew             | rgba(240, 255, 240, 1) |    |
| hotpink              | rgba(255, 105, 180, 1) |    |
| indianred            | rgba(205, 92, 92, 1)   |      |
| indigo               | rgba(75, 0, 130, 1)    |       |
| ivory                | rgba(255, 255, 240, 1) |    |
| khaki                | rgba(240, 230, 140, 1) |    |
| lavender             | rgba(230, 230, 250, 1) |    |
| lavenderblush        | rgba(255, 240, 245, 1) |    |
| lawngreen            | rgba(124, 252, 0, 1)   |      |
| lemonchiffon         | rgba(255, 250, 205, 1) |    |
| lightblue            | rgba(173, 216, 230, 1) |    |
| lightcoral           | rgba(240, 128, 128, 1) |    |
| lightcyan            | rgba(224, 255, 255, 1) |    |
| lightgoldenrodyellow | rgba(250, 250, 210, 1) |    |
| lightgray            | rgba(211, 211, 211, 1) |    |
| lightgreen           | rgba(144, 238, 144, 1) |    |
| lightgrey            | rgba(211, 211, 211, 1) |    |
| lightpink            | rgba(255, 182, 193, 1) |    |
| lightsalmon          | rgba(255, 160, 122, 1) |    |
| lightseagreen        | rgba(32, 178, 170, 1)  |     |
| lightskyblue         | rgba(135, 206, 250, 1) |    |
| lightslategray       | rgba(119, 136, 153, 1) |    |
| lightslategrey       | rgba(119, 136, 153, 1) |    |
| lightsteelblue       | rgba(176, 196, 222, 1) |    |
| lightyellow          | rgba(255, 255, 224, 1) |    |
| lime                 | rgba(0, 255, 0, 1)     |        |
| limegreen            | rgba(50, 205, 50, 1)   |      |
| linen                | rgba(250, 240, 230, 1) |    |
| magenta              | rgba(255, 0, 255, 1)   |      |
| maroon               | rgba(128, 0, 0, 1)     |        |
| mediumaquamarine     | rgba(102, 205, 170, 1) |    |
| mediumblue           | rgba(0, 0, 205, 1)     |        |
| mediumorchid         | rgba(186, 85, 211, 1)  |     |
| mediumpurple         | rgba(147, 112, 219, 1) |    |
| mediumseagreen       | rgba(60, 179, 113, 1)  |     |
| mediumslateblue      | rgba(123, 104, 238, 1) |    |
| mediumspringgreen    | rgba(0, 250, 154, 1)   |      |
| mediumturquoise      | rgba(72, 209, 204, 1)  |     |
| mediumvioletred      | rgba(199, 21, 133, 1)  |     |
| midnightblue         | rgba(25, 25, 112, 1)   |      |
| mintcream            | rgba(245, 255, 250, 1) |    |
| mistyrose            | rgba(255, 228, 225, 1) |    |
| moccasin             | rgba(255, 228, 181, 1) |    |
| navajowhite          | rgba(255, 222, 173, 1) |    |
| navy                 | rgba(0, 0, 128, 1)     |        |
| oldlace              | rgba(253, 245, 230, 1) |    |
| olive                | rgba(128, 128, 0, 1)   |      |
| olivedrab            | rgba(107, 142, 35, 1)  |     |
| orange               | rgba(255, 165, 0, 1)   |      |
| orangered            | rgba(255, 69, 0, 1)    |       |
| orchid               | rgba(218, 112, 214, 1) |    |
| palegoldenrod        | rgba(238, 232, 170, 1) |    |
| palegreen            | rgba(152, 251, 152, 1) |    |
| paleturquoise        | rgba(175, 238, 238, 1) |    |
| palevioletred        | rgba(219, 112, 147, 1) |    |
| papayawhip           | rgba(255, 239, 213, 1) |    |
| peachpuff            | rgba(255, 218, 185, 1) |    |
| peru                 | rgba(205, 133, 63, 1)  |     |
| pink                 | rgba(255, 192, 203, 1) |    |
| plum                 | rgba(221, 160, 221, 1) |    |
| powderblue           | rgba(176, 224, 230, 1) |    |
| purple               | rgba(128, 0, 128, 1)   |      |
| red                  | rgba(255, 0, 0, 1)     |        |
| rosybrown            | rgba(188, 143, 143, 1) |    |
| royalblue            | rgba(65, 105, 225, 1)  |     |
| saddlebrown          | rgba(139, 69, 19, 1)   |      |
| salmon               | rgba(250, 128, 114, 1) |    |
| sandybrown           | rgba(244, 164, 96, 1)  |     |
| seagreen             | rgba(46, 139, 87, 1)   |      |
| seashell             | rgba(255, 245, 238, 1) |    |
| sienna               | rgba(160, 82, 45, 1)   |      |
| silver               | rgba(192, 192, 192, 1) |    |
| skyblue              | rgba(135, 206, 235, 1) |    |
| slateblue            | rgba(106, 90, 205, 1)  |     |
| slategray            | rgba(112, 128, 144, 1) |    |
| slategrey            | rgba(112, 128, 144, 1) |    |
| snow                 | rgba(255, 250, 250, 1) |    |
| springgreen          | rgba(0, 255, 127, 1)   |      |
| steelblue            | rgba(70, 130, 180, 1)  |     |
| tan                  | rgba(210, 180, 140, 1) |    |
| teal                 | rgba(0, 128, 128, 1)   |      |
| thistle              | rgba(216, 191, 216, 1) |    |
| tomato               | rgba(255, 99, 71, 1)   |      |
| turquoise            | rgba(64, 224, 208, 1)  |     |
| violet               | rgba(238, 130, 238, 1) |    |
| wheat                | rgba(245, 222, 179, 1) |    |
| white                | rgba(255, 255, 255, 1) |    |
| whitesmoke           | rgba(245, 245, 245, 1) |    |
| yellow               | rgba(255, 255, 0, 1)   |      |
| yellowgreen          | 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>`](/en/api/css/data-type/number.md)s or [`<percentage>`](/en/api/css/data-type/percentage.md)s, where the number `255` corresponds to `100%`. `A` (alpha) can be a [`<number>`](/en/api/css/data-type/number.md) between 0 and 1, or a [`<percentage>`](/en/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])` or `hsl[a](H S L[ / A])`

* `H` (hue) is an [`<angle>`](/en/api/css/data-type/angle.md) of the color circle given in `deg`s, `rad`s, `grad`s. When written as a unitless [`<number>`](/en/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>`](/en/api/css/data-type/number.md) between 0 and 1, or a [`<percentage>`](/en/api/css/data-type/percentage.md), where the number `1` corresponds to `100%` (full opacity).

## Compatibility




---
url: /api/css/data-type/fit-content.md
---

# `<fit-content>`

`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



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

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

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

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

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

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

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



---
url: /api/css/data-type/gradient.md
---

# `<gradient>`

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`.&#x20;
  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>`](/en/api/css/data-type/color.md) value, followed by one stop position, a [`<percentage>`](/en/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.&#x20;
  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




---
url: /api/css/data-type/length-percentage.md
---

# `<length-percentage>`

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



[`<percentage>`]: /en/api/css/data-type/percentage.md

[`<length>`]: /en/api/css/data-type/length.md



---
url: /api/css/data-type/length.md
---

# `<length>`

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




---
url: /api/css/data-type/max-content.md
---

# `<max-content>`

`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



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

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

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

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

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

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

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



---
url: /api/css/data-type/number.md
---

# `<number>`

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




---
url: /api/css/data-type/percentage.md
---

# `<percentage>`

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>`](/en/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




---
url: /api/css/data-type/string.md
---

# `<string>`

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




---
url: /api/css/data-type/time.md
---

# `<time>`

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




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



---
url: /api/lynx-api/event/animation-event.md
---

# AnimationEvent

Represents the animation event object, inherited from [CustomEvent](/en/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`](/en/api/css/at-rule/keyframes.md) in CSS; if it is a transition animation, it is the name of [`transition-property`](/en/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




---
url: /api/lynx-api/event/custom-event.md
---

# CustomEvent

Represents a custom event object, inherited from [`Event`](/en/api/lynx-api/event/event.md), used to describe the state changes of the component customization, such as [`scroll`](/en/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




---
url: /api/lynx-api/event/event.md
---

# Event

`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](/en/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`](/en/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`](/en/api/lynx-api/event/custom-event.md)

`CustomEvent` represents a custom event object, which describes the state change of a custom component.

[`AnimationEvent`](/en/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-`](/en/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-`](/en/api/elements/built-in/view.md#data-) on `element`.

## Instance method

### stopPropagation

```ts
stopPropagation(): void;
```

Stop bubbling and prevent the event from continuing to bubble up the touch response chain.

This method is only implemented in the [main thread script](/en/react/main-thread-script.md). Calling it in the [main thread script](/en/react/main-thread-script.md) can affect both event bubbling and event handler triggering in `JS`.

### stopImmediatePropagation

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

This method is only implemented in the [main thread script](/en/react/main-thread-script.md). Calling it in the [main thread script](/en/react/main-thread-script.md) can affect both event bubbling and event handler triggering in `JS`.

## Compatibility




---
url: /api/lynx-api/event/global-event.md
---

# GlobalEvent

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`](/en/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




---
url: /api/lynx-api/event/touch-event.md
---

# TouchEvent

Represents a touch event object, inherited from [`Event`](/en/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`](/en/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`](/en/api/lynx-api/event/event.md#target) is always the same as [`target`](/en/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart).

### touchend

Indicates that the finger leaves the touch surface. [`target`](/en/api/lynx-api/event/event.md#target) is the same as [`target`](/en/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`](/en/api/lynx-api/event/event.md#target) is the same as [`target`](/en/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart). The interrupted touch point can be found in [`changedTouches`](#changedtouches).

### tap

Indicates that the finger clicks on the touch surface. [`target`](/en/api/lynx-api/event/event.md#target) is the `element` that contains the touch point and is closest to the user. Only the first finger can trigger it. When the finger moves beyond a certain threshold or triggers the `UI` at the touch position to slide, the `tap` event cannot be triggered.

In addition, this event and the [`longpress`](#longpress) event are mutually exclusive in event monitoring. That is, if the front end monitors two events at the same time, the two events will not be triggered at the same time, and [`longpress`](#longpress) takes priority.

### longpress

Indicates that the finger long presses on the touch surface. [`target`](/en/api/lynx-api/event/event.md#target) is the `element` that contains the touch point and is closest to the user. The interval for long press triggering is `500 ms`.

## Compatibility




---
url: /api/lynx-api/global.md
---




---
url: /api/lynx-api/global/clear-interval.md
---

# clearInterval() global function

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




---
url: /api/lynx-api/global/clear-timeout.md
---

# clearTimeout() global function

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




---
url: /api/lynx-api/global/console/assert.md
---

# console: assert() method

`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




---
url: /api/lynx-api/global/console/count.md
---

# console: count() method

`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




---
url: /api/lynx-api/global/console/countReset.md
---

# console: countReset() method

`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




---
url: /api/lynx-api/global/console/debug.md
---

# console: debug() method

`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




---
url: /api/lynx-api/global/console/error.md
---

# console: error() method

`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




---
url: /api/lynx-api/global/console/group.md
---

# console: group() method

`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




---
url: /api/lynx-api/global/console/groupCollapsed.md
---

# console: groupCollapsed() method

`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




---
url: /api/lynx-api/global/console/groupEnd.md
---

# console: groupEnd() method

`groupEnd` exits the current inline group in the console.

## Syntax

```ts
groupEnd(): undefined;
```

### Parameters

None.

### return value

None(`undefined`).

## Compatibility




---
url: /api/lynx-api/global/console/info.md
---

# console: info() method

`info` 方法用于在控制台面板输出信息，日志级别为 info 级别。

## Syntax

```ts
info(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

输出的JavaScript值列表。这些值中的每个值的表示形式都以给定的顺序输出。

### return value

None(`undefined`).

## Compatibility




---
url: /api/lynx-api/global/console/log.md
---

# console: log() method

`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




---
url: /api/lynx-api/global/console/profile.md
---

# console: profile() method

`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




---
url: /api/lynx-api/global/console/profileEnd.md
---

# console: profileEnd() method

`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




---
url: /api/lynx-api/global/console/table.md
---

# console: table() method

`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




---
url: /api/lynx-api/global/console/time.md
---

# console: time() method

`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




---
url: /api/lynx-api/global/console/timeEnd.md
---

# console: timeEnd() method

`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




---
url: /api/lynx-api/global/console/timeLog.md
---

# console: timeLog() method

`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




---
url: /api/lynx-api/global/console/warn.md
---

# console: warn() method

`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




---
url: /api/lynx-api/global/fetch.md
---

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

:::Caution Differences from Web

* 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

* Streaming/FormData/Blob related APIs are not supported

:::

:::Warning Web Platform Compatibility

Web Platform supports Fetch API using Browser's Fetch implementation, it follows the same rules as the web.

:::



### Headers

### Request

### Response



---
url: /api/lynx-api/global/set-interval.md
---

# setInterval() global function

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




---
url: /api/lynx-api/global/set-timeout.md
---

# setTimeout() global function

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




---
url: /api/lynx-api/global/system-info.md
---



# 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 real device.
   */
  readonly pixelRatio: number;

  /**
   * The platform of the current device.
   */
  readonly platform: 'Android' | 'iOS' | 'macOS' | 'pc' | '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.

> [systemVersion | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uidevice/1620043-systemversion?language=objc)

```objc
[[UIDevice currentDevice].systemVersion UTF8String]
```

Equivalent to the Java [`Build.VERSION.SDK_INT`](https://developer.android.com/reference/android/os/Build.VERSION#SDK_INT) API.

> [API Levels | Android NDK | Android Developers](https://developer.android.com/ndk/reference/group/apilevels#android_get_device_api_level)

```cpp
std::to_string(android_get_device_api_level())
```

#### pixelHeight

The absolute height of the available display size in pixels.

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

> [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics)

```java
DisplayMetrics dm = context.getResources().getDisplayMetrics();
// highlight-next-line
int pixelHeight = dm.heightPixels;
```

#### pixelWidth

The absolute width of the available display size in pixels.

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

> [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics)

```java
DisplayMetrics dm = context.getResources().getDisplayMetrics();
// highlight-next-line
int pixelWidth = dm.widthPixels;
```

#### pixelRatio

The natural scale factor associated with the screen.

> [UIScreen | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uiscreen?language=objc)

```objc
const CGFloat pixelRatio = [UIScreen mainScreen].scale;
```

> [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics#density)

```java
DisplayMetrics dm = context.getResources().getDisplayMetrics();
// highlight-next-line
float pixelRatio = dm.density;
```

#### platform

The platform of the current device.

Candidate values:

1. `iOS`
2. `Android`
3. `macOS`
4. `pc` (for 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




---
url: /api/lynx-api/intersection-observer.md
---

# IntersectionObserver

`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()`](/en/api/lynx-api/intersection-observer/intersection-observer-relative-to.md)

Specify the reference node, which is specified based on `id`.

[`IntersectionObserver.relativeToViewport()`](/en/api/lynx-api/intersection-observer/intersection-observer-relative-to-viewport.md)

Specify `LynxView` as the reference node.

[`IntersectionObserver.relativeToScreen()`](/en/api/lynx-api/intersection-observer/intersection-observer-relative-to-screen.md)

Specify the screen as the reference node.

[`IntersectionObserver.observer()`](/en/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()`](/en/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




---
url: /api/lynx-api/intersection-observer/intersection-observer-disconnect.md
---

# IntersectionObserver: disconnect() method

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




---
url: /api/lynx-api/intersection-observer/intersection-observer-observe.md
---

# IntersectionObserver: observe() method

`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




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to-screen.md
---

# IntersectionObserver: relativeToScreen() method

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](/en/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




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to-viewport.md
---

# IntersectionObserver: relativeToViewport() method

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](/en/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




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to.md
---

# IntersectionObserver: relativeTo() method

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](/en/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




---
url: /api/lynx-api/lynx.md
---




---
url: /api/lynx-api/lynx/lynx-add-font.md
---

# lynx: addFont() static method

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




---
url: /api/lynx-api/lynx/lynx-animate-api.md
---

# animate()

## Introduction

The `animate()` method of the `Element` is a shortcut for setting [CSS Animation](/en/api/css/properties/animation.md) on UI elements in JavaScript.

1. Use the [getElementById](/en/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',
  },
});
```

:::info Note
The Animate API also supports specify the Timing Function individually for each Keyframe segment.
:::

#### 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](/en/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](/en/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](/en/api/css/properties/animation-play-state.md)                                                                                                        | running                |

:::info Note:

1. If no 'name' is specified, a unique id generated incrementally by Lynx will be used as the name every time.
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

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

## Animation Event

The events for the `animate()` API are the same as the [animation events](/en/api/lynx-api/event/animation-event.md#animation) for CSS animations.

## Other Infos

:::info

* Animate Api and CSS Animation will override each other, and the one that takes effect later will override the former.
* Each call to `getElementById("test").animate` will generate a new `Animation` object.
* Animate Api currently only supports the creation of one animation, and will support the creation of multiple animations in the future. So now if `getElementById("test").animate` is called multiple times for a node, the last created animation will overwrite the previous animation.
* After the animation corresponding to an `Animation` object ends, if you want to restart the same animation, you need to call `getElementById("test").animate` again to create a new `Animation` object.
* Animate API currently only supports getElementById API, and the support for SelectQuery API is still being accessed.

:::

:::tip

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](/en/guide/styling/animation.md)

## Compatibility




---
url: /api/lynx-api/lynx/lynx-before-publish-event.md
---

# BeforePublishEvent

`lynx.beforePublishEvent` is used to register/remove listening for an element event.

## Instance methods

[`BeforePublishEvent.add()`](/en/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md)

Register a listener for an element event.

[`BeforePublishEvent.remove()`](/en/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




---
url: /api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md
---

# BeforePublishEvent: add() method

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




---
url: /api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md
---

# BeforePublishEvent: remove() method

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




---
url: /api/lynx-api/lynx/lynx-cancel-animation-frame.md
---

# lynx: cancelAnimationFrame() static method

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`]: /en/api/lynx-api/lynx/lynx-request-animation-frame.md

## Compatibility




---
url: /api/lynx-api/lynx/lynx-cancel-resource-prefetch.md
---

# lynx: cancelResourcePrefetch() static method

* This API is used to cancel resource preloading initiated by [requestResourcePrefetch](/en/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](/en/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




---
url: /api/lynx-api/lynx/lynx-create-intersection-observer.md
---

# lynx: createIntersectionObserver() static method

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](/en/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




---
url: /api/lynx-api/lynx/lynx-create-selector-query.md
---

# lynx: createSelectorQuery() static method

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`]: /en/api/lynx-api/selector-query.md

## Compatibility




---
url: /api/lynx-api/lynx/lynx-get-element-by-id.md
---

# getElementById()

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




---
url: /api/lynx-api/lynx/lynx-get-js-module.md
---

# lynx: getJSModule() static method

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

## Compatibility




---
url: /api/lynx-api/lynx/lynx-get-text-info.md
---

# getTextInfo()

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




---
url: /api/lynx-api/lynx/lynx-global-props.md
---

# GlobalProps

`lynx.__globalProps` is a global variable, which is an object and you can access it 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 the API provided by lynx SDK
* Every time the client performs an update, it will trigger 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>
  );
}
```

## Client side

`__globalProps` can be updated through the API 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




---
url: /api/lynx-api/lynx/lynx-performance.md
---

# lynx: performance readonly object

This object provides access to performance metrics related to the current page.

## Instance Methods

### createObserver()

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.



## Compatibility




---
url: /api/lynx-api/lynx/lynx-queue-microtask.md
---

# lynx: queueMicrotask() static method

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




---
url: /api/lynx-api/lynx/lynx-register-module.md
---

# lynx: registerModule() static method

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

## Compatibility




---
url: /api/lynx-api/lynx/lynx-reload.md
---

# lynx: reload() static method

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




---
url: /api/lynx-api/lynx/lynx-report-error.md
---

# lynx: reportError() static method

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




---
url: /api/lynx-api/lynx/lynx-request-animation-frame.md
---

# requestAnimationFrame()

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:

// Todo add example later

## Compatibility




---
url: /api/lynx-api/lynx/lynx-request-resource-prefetch.md
---

# lynx: requestResourcePrefetch() static method

* 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




---
url: /api/lynx-api/lynx/lynx-require-module-async.md
---

# lynx: requireModuleAsync() static method

Used to import modules. Just like the [`requireModule`](/en/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




---
url: /api/lynx-api/lynx/lynx-require-module.md
---

# lynx: requireModule() static method

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




---
url: /api/lynx-api/lynx/lynx-resume-exposure.md
---

# lynx: resumeExposure() static method

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.

## grammar

```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](/en/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility




---
url: /api/lynx-api/lynx/lynx-set-observer-frame-rate.md
---

# lynx: setObserverFrameRate() static method

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](/en/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility




---
url: /api/lynx-api/lynx/lynx-stop-exposure.md
---

# lynx: stopExposure() static method

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.

## grammar

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




---
url: /api/lynx-api/nodes-ref.md
---

# NodesRef

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()`](/en/api/lynx-api/nodes-ref/nodes-ref-fields.md)

Query the attributes of the selected node.

[`NodesRef.invoke()`](/en/api/lynx-api/nodes-ref/nodes-ref-invoke.md)

Execute the UI method of the selected node.

[`NodesRef.path()`](/en/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()`](/en/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




---
url: /api/lynx-api/nodes-ref/nodes-ref-fields.md
---

# NodesRef: fields() method

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




---
url: /api/lynx-api/nodes-ref/nodes-ref-invoke.md
---

# NodesRef: invoke() method

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




---
url: /api/lynx-api/nodes-ref/nodes-ref-path.md
---

# NodesRef: path() method

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




---
url: /api/lynx-api/nodes-ref/nodes-ref-set-native-props.md
---

# NodesRef: setNativeProps() method

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`](/en/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




---
url: /api/lynx-api/main-thread.md
---

# Main Thread APIs

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




---
url: /api/lynx-api/main-thread/main-thread-element.md
---

# Element

`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.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](/en/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](/en/api/lynx-api/selector-query/selector-query-select.md#selector).

```ts
const elementArray = element.querySelectorAll(selector);
```

## Compatibility




---
url: /api/lynx-api/main-thread/lynx-get-text-info.md
---

# getTextInfo()

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




---
url: /api/lynx-api/main-thread/lynx-query-selector.md
---

# lynx: querySelector(selector: string)

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](/en/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

[`MainThread.Element`](/en/api/lynx-api/main-thread/main-thread-element.md) or `null`。

## Compatibility




---
url: /api/lynx-api/main-thread/lynx-query-select-all.md
---

# lynx: querySelectorAll(selector: string)

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](/en/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

[`MainThread.Element[]`](/en/api/lynx-api/main-thread/main-thread-element.md) or `[]`。

## Compatibility




---
url: /api/lynx-api/main-thread/lynx-request-animation-frame.md
---

# requestAnimationFrame()

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:

// Todo add example later

## Compatibility




---
url: /api/lynx-api/main-thread/lynx-global-props.md
---

# GlobalProps

`lynx.__globalProps` is a global variable, which is an object and you can access it 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 the API provided by lynx SDK
* Every time the client performs an update, it will trigger 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>
  );
}
```

## Client side

`__globalProps` can be updated through the API 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




---
url: /api/lynx-api/selector-query.md
---

# SelectorQuery

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()`](/en/api/lynx-api/selector-query/selector-query-exec.md)

Execute all submitted UI node operation tasks.

[`SelectorQuery.select()`](/en/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()`](/en/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()`](/en/api/lynx-api/selector-query/selector-query-select-root.md)

Select the root node specified by `SelectorQuery`.

[`SelectorQuery.selectUniqueID()`](/en/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




---
url: /api/lynx-api/selector-query/selector-query-exec.md
---

# SelectorQuery: exec() method

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




---
url: /api/lynx-api/selector-query/selector-query-select-all.md
---

# SelectorQuery: selectAll() method

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()`](/en/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




---
url: /api/lynx-api/selector-query/selector-query-select-root.md
---

# SelectorQuery: selectRoot() method

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




---
url: /api/lynx-api/selector-query/selector-query-select-unique-id.md
---

# SelectorQuery: selectUniqueID() method

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




---
url: /api/lynx-api/selector-query/selector-query-select.md
---

# SelectorQuery: select() method

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




---
url: /api/lynx-api/performance-api.md
---

# Performance APIs

The Performance API is a set of tools for precisely measuring the performance of Lynx applications, helping developers pinpoint bottlenecks in critical phases such
as loading, rendering, and user interactions.

## Concepts and usage

The Performance API provides many built-in metrics to describe key moments at various stages of page rendering, helping developers improve page performance. It
assists developers in ensuring quick response during phases such as component rendering and user interaction. To use them, one needs to understand the following core concepts:

* Entry Object

  [`lynx.performance`](/api/lynx-api/lynx/lynx-performance.md) serves as the entry point to the performance monitoring system.

* Performance Observer

  The [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md) interface is used to listen for various types of performance entries.

* Performance Events

  Performance events are represented by [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md). `PerformanceEntry` includes basic information such as
  the event name `name` and event type `entryType`. All performance events (e.g., application initialization time, page load time) inherit from the `PerformanceEntry`
  interface and extend it with additional properties.

## Guides

The following guides help you to understand key concepts of the Performance API and provide an overview about its abilities:

* [Evaluating Performance](/guide/performance/evaluating-performance.md): This is the core guide for evaluating page performance. The article highlights crucial
  performance metrics to focus on and demonstrates their application in typical scenarios.
* [Timing Flag](/guide/performance/timing-flag.md): Timing Flags can help you track the performance of important data updates. This article explains how to use
  `__lynx_timing_flag` to monitor the [Lynx Pipeline](/guide/spec.md#lynx-pipeline).



---
url: /api/lynx-api/performance-api/performance-entry.md
---



# PerformanceEntry

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

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

The corresponding subclasses for each entryType value are shown in the table below.

| entryType  |                                                                                                     subclasses                                                                                                      |
| :--------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|   `init`   | [`InitContainerEntry`](/en/api/lynx-api/performance-api/performance-entry/init-container-entry.md), [`InitLynxviewEntry`](/en/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md), [`InitBackgroundRuntimeEntry`](/en/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md) |
|  `metric`  |                                           [`MetricFcpEntry`](/en/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md), [`MetricActualfmpEntry`](/en/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md)                                           |
| `pipeline` |                                                  [`PipelineEntry`](/en/api/lynx-api/performance-api/performance-entry/pipeline-entry.md), [`LoadBundleEntry`](/en/api/lynx-api/performance-api/performance-entry/load-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`](/en/api/lynx-api/performance-api/performance-entry/init-container-entry.md)          |                                       `container`                                        |
|          [`InitLynxviewEntry`](/en/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md)           |                                        `lynxview`                                        |
| [`InitBackgroundRuntimeEntry`](/en/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md) |                                   `backgroundRuntime`                                    |
|             [`MetricFcpEntry`](/en/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md)              |                                          `fcp`                                           |
|       [`MetricActualFmpEntry`](/en/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md)       |                                       `actualFmp`                                        |
|               [`PipelineEntry`](/en/api/lynx-api/performance-api/performance-entry/pipeline-entry.md)               | `updateTriggeredByBts`, `updateTriggeredByNative`, `updateGlobalProps`, `setNativeProps` |
|            [`LoadBundleEntry`](/en/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md)             |                      `loadBundle`, `reloadBundle`, `reloadFromBts`                       |

## Compatibility




---
url: /api/lynx-api/performance-api/performance-entry/init-container-entry.md
---

# InitContainerEntry

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



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




---
url: /api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md
---

# InitLynxviewEntry

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



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




---
url: /api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md
---

# InitBackgroundRuntimeEntry

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



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




---
url: /api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md
---

# MetricFcpEntry

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`](/en/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:

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:

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



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




---
url: /api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md
---

# MetricActualFmpEntry

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`](/en/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/timing-flag.md).

In the "real data" rendering, the timing for Actual FMP is as follows:

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:

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



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




---
url: /api/lynx-api/performance-api/performance-entry/pipeline-entry.md
---



# PipelineEntry

`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`](/en/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/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`:

## Example

This example demonstrates how to generate and retrieve `PipelineEntry`.



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

## Compatibility




---
url: /api/lynx-api/performance-api/performance-entry/load-bundle-entry.md
---

# LoadBundleEntry

*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`](/en/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

The LoadBundle process flowchart is as follows:

## Example

This example demonstrates how to obtain a `LoadBundleEntry`.



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

## Compatibility




---
url: /api/lynx-api/performance-api/performance-observer.md
---



# PerformanceObserver

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()`](/en/api/lynx-api/performance-api/performance-observer/observe.md)

Specify a set of performance entry types to observe and start observing.

[`PerformanceObserver.disconnect()`](/en/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`](/en/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`pipeline`](/en/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) entries.



## Compatibility




---
url: /api/lynx-api/performance-api/performance-observer/observe.md
---



# PerformanceObserver: observe() method

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



### Observing specific performance events

This example creates a `PerformanceObserver` that observes `MetricFcpEntry` and the entire `PerformanceEntry` of type `pipeline` through `["metric.fcp", "pipeline"]`.

## Compatibility




---
url: /api/lynx-api/performance-api/performance-observer/disconnect.md
---



# PerformanceObserver: disconnect() method

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.



## Compatibility




---
url: /api/lynx-api/performance-api/performance-metric.md
---



# PerformanceMetric

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`](/en/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/en/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`](/en/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`](/en/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




---
url: /api/lynx-api/performance-api/framework-pipeline-timing.md
---



# FrameworkPipelineTiming

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




---
url: /api/lynx-native-api/lynx-view.md
---




---
url: /api/lynx-native-api/lynx-view/add-lynx-view-client.md
---

# addLynxViewClient

Register lifecycle event observer for `LynxView`

## Syntax

### Android

```java
public void addLynxViewClient(LynxViewClient client);
```

### Parameters

* `client: 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;

### iOS

```objc
- (void)addLifecycleClient:(nonnull id<LynxViewLifecycle>)lifecycleClient;
```

### Parameters

* `lifecycleClient: id<LynxViewLifecycle>`: 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;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/destroy.md
---

# destroy

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




---
url: /api/lynx-native-api/lynx-view/find-ui-by-idselector.md
---

# findUIByIdSelector

Find `LynxUI` nodes based on the idSelector attribute

## Syntax

### Android

```java
public LynxBaseUI findUIByIdSelector(String id);
```

### Parameters

* `id: String`: The id attribute of the view specified by the front end in the layout file;

### iOS

```objc
- (nullable LynxUI*)uiWithIdSelector:(nonnull NSString*)idSelector;
```

### Parameters

* `idSelector: NSString*`: The id attribute of the view specified by the front end in the layout file;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/find-ui-by-name.md
---

# findUIByName

Find `LynxUI` nodes based on the `name` attribute;

## Syntax

### Android

```java
public LynxBaseUI findUIByName(String name);
```

### Parameters

* `name: String`: The name attribute of the view specified by the front end in the layout file;

### iOS

```objc
- (nullable LynxUI*)uiWithName:(nonnull NSString*)name;
```

### Parameters

* `name: NSString*`: The name attribute of the view specified by the front end in the layout file;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/find-view-by-idselector.md
---

# findViewByIdSelector

Find `UIView` based on `idSelector` property

## Syntax

### Android

```java
public LynxBaseUI findUIByIdSelector(String id);
```

### Parameters

* `id: String`: The id attribute of the view specified by the front end in the layout file;

### iOS

```objc
- (nullable LynxUI*)uiWithIdSelector:(nonnull NSString*)idSelector;
```

## Parameters

* `idSelector: NSString*`: The id attribute of the view specified by the front end in the layout file;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/find-view-by-name.md
---

# findViewByIdName

Find `UIView` based on `name` attribute

## Syntax

### Android

```java
public View findViewByName(String name);
```

### Parameters

* `name: String`: The name attribute of the view specified by the front end in the layout file;

### iOS

```objc
- (nullable UIView*)viewWithName:(nonnull NSString*)name;
```

### Parameters

* `name: NSString*`: The name attribute of the view specified by the front end in the layout file;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/load-template.md
---

# LoadTemplate

Using [`LynxLoadMeta`](/en/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
void loadTemplate(@NonNull LynxLoadMeta meta);
```

### Parameters

* `meta: LynxLoadMeta`: Lynx template loads metadata, and developers use this data structure to specify optional data loaded by the template.

### iOS

```objc
- (void)loadTemplate:(nonnull LynxLoadMetadata*)meta;
```

### Parameters

* `meta: LynxLoadMetadata*`: Lynx template loads metadata, and developers use this data structure to specify optional data loaded by the template.

## Compatibility




---
url: /api/lynx-native-api/lynx-view/remove-lynx-view-client.md
---

# removeLynxViewClient

remove `LynxView` lifecycle event monitoring;

## Syntax

### Android

```java
public void removeLynxViewClient(LynxViewClient client)
```

## Parameters

* `client: 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 life cycle.

## Compatibility




---
url: /api/lynx-native-api/lynx-view/send-global-event.md
---

# sendGlobalEvent

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: String`: Global event name;
* `params: `: Parameters carried by global events;

### iOS

```objc
- (void)sendGlobalEvent:(nonnull NSString*)name withParams:(nullable NSArray*)params;
```

### Parameters

* `name: NSString*`: global event name;
* `params: NSArray*`: Parameters carried by global events;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/set-extra-timing.md
---

# setExtraTiming

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: TimingHandler.ExtraTimingInfo`: 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: LynxExtraTiming*`: 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




---
url: /api/lynx-native-api/lynx-view/update-data.md
---

# UpdateData

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
void updateData(LynxUpdateMeta meta)
```

### Parameters

* `meta: LynxUpdateMeta`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template;

### iOS

```objc
(void)updateData:(nonnull LynxUpdateMeta*)meta;
```

### Parameters

* `meta: LynxUpdateMeta*`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/update-font-scale.md
---

# updateFontScale

Changing the font scaling ratio in client settings will automatically change the text size;

## Syntax

### Android

```java
public void updateFontScale(float scale);
```

### Parameters

* `scale: float`: font scaling;

### iOS

```objc
- (void)updateFontScale:(CGFloat)scale;
```

### Parameters

* `scale: CGFloat`: Font scaling;

## Compatibility




---
url: /api/lynx-native-api/lynx-view/update-viewport.md
---

# updateViewport

The client updates the `LynxView` view size;

## Syntax

### Android

```java
public void updateViewport(int widthMeasureSpec, int heightMeasureSpec)
```

### Parameters

* `widthMeasureSpec: int`: current `LynxView` width;
* `heightMeasureSpec: int`: current `LynxView` height;

### iOS

```objc
- (void)updateViewportWithPreferredLayoutWidth:(CGFloat)preferredLayoutWidth
                        preferredLayoutHeight:(CGFloat)preferredLayoutHeight;

- (void)updateViewportWithPreferredLayoutWidth:(CGFloat)preferredLayoutWidth
                         preferredLayoutHeight:(CGFloat)preferredLayoutHeight
                                    needLayout:(BOOL)needLayout;
```

### Parameters

* `preferredLayoutWidth: CGFloat`: current `LynxView` width;
* `preferredLayoutHeight: CGFloat`: current `LynxView` height;
* `needLayout: BOOL`: whether layout needs to be triggered;

## Compatibility




---
url: /api/lynx-native-api/lynx-load-meta.md
---

# LynxMetaData

`LynxLoadMeta` is the metadata structure used by `LynxView` to load templates. It will be used as the input parameter of [loadTemplate](/en/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](/en/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;
* `loadOptions: EnumSet<LynxLoadOption>`: Additional configuration information when loading templates;

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

:::

### 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.addLoadOption();
LynxLoadMeta meta = builder.build();
```

## iOS

### Field

* `url: NSString*`: Template file path;
* `binaryData: NSData*`: The binary file data of the template;
* `templateBundle: LynxTemplateBundle*`: [TemplateBundle](/en/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;
* `loadOptions: LynxLoadOption`: Additional configuration information when loading templates;

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

:::

### 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.loadOption = LynxLoadOptionDumpElement | LynxLoadOptionRecycleTemplateBundle;
```

## Compatibility




---
url: /api/lynx-native-api/lynx-update-meta.md
---

# LynxUpdateMeta

LynxUpdateMeta is the metadata structure used by LynxView to update template data. It will serve as the input parameter for [UpdateData](/en/api/lynx-native-api/lynx-view/update-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;
```

## Compatibility




---
url: /api/lynx-native-api/template-bundle.md
---

# TemplateBundle

`TemplateBundle` is the output product of the PreDecode capability provided by the Lynx SDK. Client developers can parse the Lynx template product in advance to obtain the `TemplateBundle` object and consume the template product.

## Android

#### fromTemplate

```java
public static TemplateBundle fromTemplate(byte[] template)
```

Input Lynx template binary content and return the parsed `TemplateBundle` object.

Params:

* template: byte\[]: Template binary content;

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;

#### getExtraInfo

```java
public Map<String, Object> getExtraInfo()
```

Read the content of the `extraInfo` field configured in the `pageConfig` of the front-end template. When the front-end does not configure `extraInfo` or is called on an empty `TemplateBundle` object, it returns `null`;

#### isValid

```java
public boolean isValid()
```

Determines whether the current `TemplateBundle` object is valid.

#### getErrorMessage

```java
public String getErrorMessage()
```

When `TemplateBundle` is an invalid object, use this method to obtain the exception information that occurred during template parsing;

#### postJsCacheGenerationTask

```java
public void postJsCacheGenerationTask(String codeCacheSourceUrl, boolean useV8)
```

Start a sub-thread task to generate the `js code cache` of the current template;

Params:

* `codeCacheSourceUrl: String`: The `url` of the current template;
* `useV8: boolean`: Whether to generate `V8 Code Cache`, otherwise generate `QuickJS Code Cache`;

#### release

```java
public void release();
```

Release the `Native` memory held by the current `TemplateBundle` object. After executing the `release` method, the `TemplateBundle` will become the `inValid` state;

## iOS

#### initWithTemplate

```objective-c
- (instancetype _Nullable)initWithTemplate:(nonnull NSData*)tem;
```

Input Lynx template binary content and return the parsed `LynxTemplateBundle` object.

Params:

* `tem: NSData*`: Template binary content;

Note:

* When the input `tem` is not a correct `Lynx` template data, or is `nil`, an invalid `TemplateBundle` is returned;

#### errorMsg

```objective-c
- (NSString* _Nullable)errorMsg;
```

Use this method to obtain the exception information that occurs during template parsing; if `nil` is returned, it proves that the `LynxTemplateBundle` is normal;

#### extraInfo

```objective-c
- (NSDictionary* _Nullable)extraInfo;
```

Read the content of the `extraInfo` field configured in the `pageConfig` of the front-end template. When the front-end does not configure `extraInfo` or is called on an empty `TemplateBundle` object, it returns `null`;

## Compatibility




---
url: /api/lynx-native-api/template-data.md
---

# TemplateData

TemplateData is a data structure provided by Lynx. It is used to store the data types accepted by Lynx at runtime and can be constructed using either a string or a map type.

## Android

#### fromMap

```java
public static TemplateData fromMap(Map<String, Object> map)
```

Input `Map` type data and return the parsed `TemplateData` object.

Params:

* `map: Map<String, Object>`: `Map` type data;

#### fromString

```java
public static TemplateData fromString(String json)
```

Input `String` type data and return the parsed `TemplateData` object.

Params:

* `json: String`: `String` type data;

#### markState

```java
public void markState(String name)
```

Mark the current TemplateData with the associated dataProcessor name. When this TemplateData is used in [UpdateData](/api/lynx-native-api/lynx-view/update-data.md), the corresponding dataProcessor will be found based on this name for data preprocessing.

Params:

* `name: String`: Marked name;

## iOS

#### initWithDictionary

```objective-c
- (instancetype)initWithDictionary:(NSDictionary *)dictionary;
```

Input `NSDictionary` type data and return the parsed `LynxTemplateData` object.

Params:

* `dictionary: NSDictionary*`: `NSDictionary*` type data;

#### initWithJson

```objective-c
- (instancetype)initWithJson:(NSString *)json;
```

Input `NSDictionary` type data and return the parsed `LynxTemplateData` object.

Params:

* `json: NSString*`: `NSString*` type data;

#### markState

```objective-c
- (void)markState:(NSString *)name;
```

Mark the current TemplateData with the associated dataProcessor name. When this TemplateData is used in [UpdateData](/api/lynx-native-api/lynx-view/update-data.md), the corresponding dataProcessor will be found based on this name for data preprocessing.

Params:

* `name: NSString*`: Marked name;

## Compatibility




---
url: /api/lynx-native-api/resource-fetcher/GenericResourceFetcher.md
---



# LynxGenericResourceFetcher

`LynxGenericResourceFetcher` is defined inside `LynxEngine` and injected from outside to implement a general resource loading interface. It is used inside LynxEngine for resource loading capabilities of components such as `Text`;

## Android

### Interface Definition:

```java title=LynxGenericResourceFetcher.java
public abstract class LynxGenericResourceFetcher {
  /**
   * fetch resource with contents.
   *
   * @param request
   * @param callback contents of the requiring resource.
   */
  public abstract void fetchResource(
      LynxResourceRequest request, LynxResourceCallback<byte[]> callback);

  /**
   * fetch resource with res path.
   *
   * @param request
   * @param callback path on the disk of the requiring resource.
   */
  public abstract void fetchResourcePath(
      LynxResourceRequest request, LynxResourceCallback<String> callback);

  /**
   * fetch resource with stream.
   *
   * @param request
   * @param delegate streaming of the requiring resource.
   */
  public void fetchStream(LynxResourceRequest request, StreamDelegate delegate){};

  /**
   * cancel the request of the requiring resource.
   *
   * @param request the requiring request.
   */
  public void cancel(LynxResourceRequest request){};
}
```

### Method Introduction:

#### fetchResource

`LynxEngine` internally calls this method to obtain the general resource content, and the return result is required to be the resource content `byte[]` type;

:::note
This method must be implemented;
:::

#### fetchResourcePath

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

:::note
This method must be implemented;
:::

#### fetchStream

`LynxEngine` internally calls this method to obtain resource content in a streaming manner;

:::note
This method must be implemented;
:::

### Injection:

Inject when constructing a LynxView using LynxViewBuilder:

```java
LynxViewBuilder builder = new LynxViewBuilder();
builder.setGenericResourceFetcher(new GenericTemplateResourceFetcher());
```

Also enable this capability in `LynxViewBuilder`:

```java
LynxViewBuilder builder = new LynxViewBuilder();
builder.setGenericResourceFetcher(new GenericTemplateResourceFetcher());
builder.setEnableGenericResourceFetcher(LynxBooleanOption.TRUE);
```

## iOS

### Interface Definition:

```objective-c title=LynxGenericResourceFetcher.h
@protocol LynxGenericResourceFetcher <NSObject>

/**
 * fetch resource with contents.
 *
 * @param request.
 * @param callback contents of the requiring resource.
 *
 * @return: A block which can cancel the image request if it is not finished. nil if cancel action
 * is not supported.
 */
@required
- (dispatch_block_t)fetchResource:(nonnull LynxResourceRequest *)request
                       onComplete:(LynxGenericResourceCompletionBlock _Nonnull)callback;

/**
 * fetch resource with res path.
 *
 * @param request
 * @param callback path on the disk of the requiring resource.
 *
 * @return: A block which can cancel the image request if it is not finished. nil if cancel action
 * is not supported.
 */
@required
- (dispatch_block_t)fetchResourcePath:(nonnull LynxResourceRequest *)request
                           onComplete:(LynxGenericResourcePathCompletionBlock _Nonnull)callback;

/**
 * fetch resource with stream.
 *
 * @param request
 * @param delegate streaming of the requiring resource.
 *
 * @return: A block which can cancel the image request if it is not finished. nil if cancel action
 * is not supported.
 */
@optional
- (dispatch_block_t)fetchStream:(nonnull LynxResourceRequest *)request
                     withStream:(nonnull id<LynxResourceStreamLoadDelegate>)delegate;

@end
```

### Method Introduction:

#### fetchResource

`LynxEngine` internally calls this method to obtain the general resource content, and the return result is required to be the resource content `byte[]` type;

:::note
This method must be implemented;
:::

#### fetchResourcePath

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

:::note
This method must be implemented;
:::

#### fetchStream

`LynxEngine` internally calls this method to obtain resource content in a streaming manner;

:::note
This method must be implemented;
:::

### Injection:

Inject when constructing a LynxView using LynxViewBuilder:

```objective-c
LynxViewBuilder *builder = [[LynxViewBuilder alloc] init];
builder.genericResourceFetcher = [[ExampleGenericResourceFetcher alloc] init];
```

Also enable this capability in `LynxViewBuilder`:

```objective-c
LynxViewBuilder *builder = [[LynxViewBuilder alloc] init];
builder.genericResourceFetcher = [[ExampleGenericResourceFetcher alloc] init];
builder.enableGenericResourceFetcher = LynxBooleanOptionTrue;
```

## Compatibility




---
url: /api/lynx-native-api/resource-fetcher/MediaResourceFetcher.md
---



# LynxMediaResourceFetcher

`LynxMediaResourceFetcher` is defined inside LynxEngine and injected from outside to implement the path redirection capability of `Image` and other third-party resources.

## Android

### Interface Definition:

```java title=LynxMediaResourceFetcher.java
public abstract class LynxMediaResourceFetcher {
  public abstract String shouldRedirectUrl(LynxResourceRequest request);

  /**
   * Quick check for a local path.
   *
   * @param url input path
   * @return
   *  TRUE if is a local path;
   *  FALSE if not a local path;
   *  UNDEFINED if not sure;
   */
  public OptionalBool isLocalResource(String url) {
    return OptionalBool.UNDEFINED;
  }

  /**
   * fetch Image Drawable directly.
   *
   * @param request
   * @param callback Response with the needed drawable.
   */
  public void fetchImage(LynxResourceRequest request, LynxResourceCallback<Closeable> callback) {}
}
```

### Method introduction:

#### shouldRedirectUrl

`LynxEngine` redirects the image path by calling this method internally, and the return result is required to be of `String` type;

:::note
This method must be implemented;
:::

#### isLocalResource

`LynxEngine` internally calls this method to determine whether the resource path exists on disk;

:::note
This method must be implemented;
:::

#### fetchImage

`LynxEngine` will use this method to obtain the bitmap information of the image, and the return content must be of `Closeable` type;

:::note
This method is optional to implement;
:::

### Injection:

Inject when constructing a LynxView using LynxViewBuilder:

```java
LynxViewBuilder builder = new LynxViewBuilder();
builder.setMediaResourceFetcher(new MediaTemplateResourceFetcher());
```

Also enable this capability in `LynxViewBuilder`:

```java
LynxViewBuilder builder = new LynxViewBuilder();
builder.setMediaResourceFetcher(new MediaTemplateResourceFetcher());
builder.setEnableGenericResourceFetcher(LynxBooleanOption.TRUE);
```

## iOS

### Interface Definition:

```objective-c title=LynxMediaResourceFetcher.h
@protocol LynxMediaResourceFetcher <NSObject>

@required
- (NSString* _Nonnull)shouldRedirectUrl:(LynxResourceRequest* _Nonnull)request;

/**
 * Quick check for a local path.
 *
 * @param url input path
 * @return TRUE if is a local path; FALSE if not a local path
 */
@optional
- (LynxResourceOptionalBool)isLocalResource:(NSURL* _Nonnull)url;

/**
 * fetch UIImage directly.
 *
 * @param request
 * @param callback Response with the needed uiImage.
 *
 * @return A block which can cancel the image request if it is not finished. nil if cancel action is
 * not supported.
 */
@optional
- (dispatch_block_t)fetchUIImage:(LynxResourceRequest* _Nonnull)request
                      onComplete:(LynxMediaResourceCompletionBlock _Nonnull)response;

@end
```

### Method introduction:

#### shouldRedirectUrl

`LynxEngine` redirects the image path by calling this method internally, and the return result is required to be of `String` type;

:::note
This method must be implemented;
:::

#### isLocalResource

`LynxEngine` internally calls this method to determine whether the resource path exists on disk;

:::note
This method is optional to implement;
:::

#### fetchUIImage

`LynxEngine` will use this method to obtain the bitmap information of the image, and the return content must be of `Closeable` type;

:::note
This method is optional to implement;
:::

### Injection:

Inject when constructing a LynxView using LynxViewBuilder:

```objective-c
LynxViewBuilder *builder = [[LynxViewBuilder alloc] init];
builder.mediaResourceFetcher = [[ExampleMediaResourceFetcher alloc] init];
```

Also enable this capability in `LynxViewBuilder`:

```objective-c
LynxViewBuilder *builder = [[LynxViewBuilder alloc] init];
builder.mediaResourceFetcher = [[ExampleMediaResourceFetcher alloc] init];
builder.enableGenericResourceFetcher = LynxBooleanOptionTrue;
```

## Compatibility




---
url: /api/lynx-native-api/resource-fetcher/TemplateResourceFetcher.md
---



# LynxTemplateResourceFetcher

`LynxTemplateResourceFetcher` is defined inside LynxEngine and injected from outside to implement the resource loading interface of [Bundle](/guide/spec.md#lynx-bundle-or-bundle) and [Lazy Bundle](/guide/spec.md#lazy-bundle) etc.

## Android

### Interface definition:

```java title=LynxTemplateResourceFetcher.java
abstract class LynxTemplateResourceFetcher {

   @Required
   void fetchTemplate(LynxResourceRequest request, LynxResourceCallBack<TemplateProviderResult> callback);

}
```

### Method introduction:

#### fetchTemplate

`LynxEngine` internally calls this method to obtain the contents of Bundle and Lazy Bundle. The returned result type can contain `byte[]` or `TemplateBundle`;

:::note
This method must be implemented;
:::

### Injection:

Inject when constructing a LynxView using LynxViewBuilder:

```java
LynxViewBuilder builder = new LynxViewBuilder();
builder.setTemplateResourceFetcher(new ExampleTemplateResourceFetcher());
```

Also enable this capability in `LynxViewBuilder`:

```java
LynxViewBuilder builder = new LynxViewBuilder();
builder.setTemplateResourceFetcher(new ExampleTemplateResourceFetcher());
builder.setEnableGenericResourceFetcher(LynxBooleanOption.TRUE);
```

## iOS

### Interface definition:

```objective-c title=LynxTemplateResourceFetcher.h
@protocol LynxTemplateResourceFetcher <NSObject>

/**
 * fetch Bundle etc.
 *
 * @param request
 * @param callback response with the requiring content file: NSData* or TemplateBundle
 */
@required
- (void)fetchTemplate:(LynxResourceRequest* _Nonnull)request
           onComplete:(LynxTemplateResourceCompletionBlock _Nonnull)callback;

@end

NS_ASSUME_NONNULL_END
```

### Method introduction:

#### fetchTemplate

`LynxEngine` internally calls this method to obtain the contents of `AppBundle` and `LazyBundle`. The returned result type can contain `NSData*` or `TemplateBundle`;

:::note
This method must be implemented;
:::

### Injection:

Inject when constructing a LynxView using LynxViewBuilder:

```objective-c
LynxViewBuilder *builder = [[LynxViewBuilder alloc] init];
builder.templateResourceFetcher = [[ExampleTemplateResourceFetcher alloc] init];
```

Also enable this capability in `LynxViewBuilder`:

```objective-c
LynxViewBuilder *builder = [[LynxViewBuilder alloc] init];
builder.templateResourceFetcher = [[ExampleTemplateResourceFetcher alloc] init];
builder.enableGenericResourceFetcher = LynxBooleanOptionTrue;
```

## Compatibility




---
url: /api/lynx-native-api/lynx-service.md
---

# LynxService API



## Introduction

Lynx Service provides Lynx Engine with host-specific capabilities, including image, log, and [FetchAPI](/guide/interaction/networking.md#fetch-api) capabilities.
Different hosts have specific requirements for their own image, log, and network libraries, so Lynx Engine opens up autonomous access capabilities for such scenarios through the LynxService API.

## Overall Design

Lynx Engine and Lynx Service adopt a dependency-separation design. In terms of the dependency relationship, Lynx Service depends on the LynxService API provided by Lynx Engine to implement itself, while Lynx Engine does not depend on LynxService. At runtime, Lynx Engine will search for the registered Lynx Service through the service lookup mechanism and call it via the LynxService API.

## LynxService API

The LynxService API is provided by Lynx Engine and is designed to specify the capabilities of LynxService. Lynx Service needs to correctly implement itself in accordance with the requirements of the LynxService API to ensure that Lynx Engine can properly use this basic capability.

## 1. Quick Access

Lynx provides a default implementation of Lynx Service, which can be directly [accessed](/guide/start/integrate-with-existing-apps.md)

## 2. Lynx Service Customization

If there are custom requirements, you can also quickly implement and register relevant content according to your own needs. The following will take log service as an example to introduce how to implement and register a custom Lynx Service:

### Interface Implementation

* 1. Implement `LynxServiceLogProtocol`

```objective-c title="YourLogService.h"
#import <Lynx/LynxService.h>
#import <Lynx/LynxServiceLogProtocol.h>

// Implement LynxServiceLogProtocol
@interface YourLogService : NSObject <LynxServiceLogProtocol>
@end
```

* 2. Use the `LynxServiceRegister` to achieve automatic registration.
* 3. Implement `serviceBizID` and `serviceScope`. These two methods have no practical significance and will be removed later.
* 4. Implement `serviceType`. It is required to return the type implemented by this Service. See LynxService.h for details.
* 5. (Recommended) Implement `sharedInstance` to make it a singleton class. Based on the current Lynx Service design, only one instance of a certain type of Service will be used globally. It is recommended to implement it as a singleton class.
* 6. Implement all the interfaces required by `LynxServiceLogProtocol`.

```objective-c title="YourLogService.mm"
#import "YourLogService.h"

[[maybe_unused]] void logWrite(unsigned int level, const char *tag, const char *format) {
  if (format == NULL) {
    return;
  }
  NSLog(@"[%s] %s", tag == NULL ? "" : tag, format);
}

// Use the LynxServiceRegister macro to achieve automatic registration
@LynxServiceRegister(LynxLogService);

// Implement LynxLogService
@implementation LynxLogService

// Irrelevant property, will be removed later
+ (NSString*)serviceBizID {
  return DEFAULT_LYNX_SERVICE;
}

// Irrelevant property, will be removed later
+ (LynxServiceScope)serviceScope {
  return LynxServiceScopeDefault;
}

// Return the corresponding service type for runtime lookup
+ (NSUInteger)serviceType {
  return kLynxServiceLog;
}

// Recommended: Implement as a singleton
+ (instancetype)sharedInstance {
  static dispatch_once_t onceToken;
  static YourLogService *logService;
  dispatch_once(&onceToken, ^{
    logService = [[YourLogService alloc] init];
  });
  return logService;
}

// Implement all the interfaces required by LynxServiceLogProtocol
- (void *)getWriteFunction {
  return (void *)logWrite;
}

@end
```

Implement `ILynxLogService`：

```kotlin title="YourLogService.kt"
object YourLogService : ILynxLogService {
  private var logOutputChannel: LogOutputChannelType = LogOutputChannelType.Platform

  override fun logByPlatform(
    level: Int,
    tag: String,
    msg: String,
  ) {
    // Implemention
  }

  override fun isLogOutputByPlatform(): Boolean = logOutputChannel == LogOutputChannelType.Platform

  override fun getDefaultWriteFunction(): Long = 0

  override fun switchLogToSystem(enableSystemLog: Boolean) {}

  override fun getLogToSystemStatus(): Boolean = false
}
```

### Service Register

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.2.0-rc.0', :subspecs => [
      'Image',
-     'Log',
      'Http',
  ]
```

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



---
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](https://lynxjs.org/api/engine/element-api), notably the [Element PAPI](https://lynxjs.org/api/engine/element-api) and [Dual-threaded Model](https://lynxjs.org/guide/spec#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](https://lynxjs.org/react/reactlynx-testing-library.html) 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](https://lynxjs.org/guide/spec.html),
notably the [Element PAPI](https://lynxjs.org/api/engine/element-api) and [Dual-threaded Model](https://lynxjs.org/guide/spec#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](https://lynxjs.org/guide/spec.html), notably the [Element PAPI](https://lynxjs.org/api/engine/element-api) and [Dual-threaded Model](https://lynxjs.org/guide/spec#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/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](https://lynxjs.org/guide/spec.html),
notably the [Element PAPI](https://lynxjs.org/api/engine/element-api) and [Dual-threaded Model](https://lynxjs.org/guide/spec#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](https://lynxjs.org/living-spec/index.html?ts=1743416098203#element%E2%91%A0)

## Extends

* `HTMLElement`

## Properties

### cssId?

```ts
optional cssId: string;
```

The cssId of the element

#### Defined in

lynx/ElementPAPI.d.ts:24

***

### eventMap?

```ts
optional eventMap: object;
```

The map of events bound to the element.

#### Index Signature

\[`key`: `string`]: `any`

#### Defined in

lynx/ElementPAPI.d.ts:12

***

### firstChild

```ts
firstChild: LynxElement;
```

Returns the first child.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/firstChild)

#### Defined in

lynx/ElementPAPI.d.ts:30

***

### gesture?

```ts
optional gesture: object;
```

The gestures bound to the element.

#### Index Signature

\[`key`: `string`]: `any`

#### Defined in

lynx/ElementPAPI.d.ts:18

***

### nextSibling

```ts
nextSibling: LynxElement;
```

Returns the next sibling.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/nextSibling)

#### Defined in

lynx/ElementPAPI.d.ts:36

***

### parentNode

```ts
parentNode: LynxElement;
```

Returns the parent.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/parentNode)

#### Defined in

lynx/ElementPAPI.d.ts:42



---
url: /api/lynx-testing-environment/Interface.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/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](https://lynxjs.org/guide/spec.html), notably the [Element PAPI](https://lynxjs.org/api/engine/element-api) and [Dual-threaded Model](https://lynxjs.org/guide/spec#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 |
| [logDOM](/api/reactlynx-testing-library/Function.logDOM.md) | - |
| [logRoles](/api/reactlynx-testing-library/Function.logRoles.md) | - |
| [prettyDOM](/api/reactlynx-testing-library/Function.prettyDOM.md) | - |
| [queryAllByAltText](/api/reactlynx-testing-library/Function.queryAllByAltText.md) | - |
| [queryAllByAttribute](/api/reactlynx-testing-library/Function.queryAllByAttribute.md) | - |
| [queryAllByDisplayValue](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md) | - |
| [queryAllByLabelText](/api/reactlynx-testing-library/Function.queryAllByLabelText.md) | - |
| [queryAllByPlaceholderText](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md) | - |
| [queryAllByRole](/api/reactlynx-testing-library/Function.queryAllByRole.md) | - |
| [queryAllByTestId](/api/reactlynx-testing-library/Function.queryAllByTestId.md) | - |
| [queryAllByText](/api/reactlynx-testing-library/Function.queryAllByText.md) | - |
| [queryAllByTitle](/api/reactlynx-testing-library/Function.queryAllByTitle.md) | - |
| [queryByAltText](/api/reactlynx-testing-library/Function.queryByAltText.md) | - |
| [queryByAttribute](/api/reactlynx-testing-library/Function.queryByAttribute.md) | - |
| [queryByDisplayValue](/api/reactlynx-testing-library/Function.queryByDisplayValue.md) | - |
| [queryByLabelText](/api/reactlynx-testing-library/Function.queryByLabelText.md) | - |
| [queryByPlaceholderText](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md) | - |
| [queryByRole](/api/reactlynx-testing-library/Function.queryByRole.md) | - |
| [queryByTestId](/api/reactlynx-testing-library/Function.queryByTestId.md) | - |
| [queryByText](/api/reactlynx-testing-library/Function.queryByText.md) | - |
| [queryByTitle](/api/reactlynx-testing-library/Function.queryByTitle.md) | - |
| [render](/api/reactlynx-testing-library/Function.render.md) | Render into the page. It should be used with cleanup. |
| [renderHook](/api/reactlynx-testing-library/Function.renderHook.md) | Allows you to render a hook within a test React component without having to create that component yourself. |
| [waitFor](/api/reactlynx-testing-library/Function.waitFor.md) | - |
| [waitForElementToBeRemoved](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md) | - |
| [waitSchedule](/api/reactlynx-testing-library/Function.waitSchedule.md) | Wait for the next event loop. |
| [within](/api/reactlynx-testing-library/Function.within.md) | - |



---
url: /api/reactlynx-testing-library/Class.LynxTestingEnv.md
---

{/*
  * 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](https://lynxjs.org/guide/spec.html),
notably the [Element PAPI](https://lynxjs.org/api/engine/element-api) and [Dual-threaded Model](https://lynxjs.org/guide/spec#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

## 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](https://lynxjs.org/zh/guide/interaction/ifr.html) 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/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/engine/element-api.md
---


This section aims to introduce the [Element PAPI](/guide/spec.html#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/__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/lynx-error.md
---

# LynxError

`LynxError` is the structure used to represent an error,
carrying several properties such as code, subcode, level, and error message.
Developers can utilize the attributes and methods for troubleshooting.

## Android

#### getErrorCode

```java
public int getErrorCode()
```

Return the error code. The error code is a 3 to 4-digit number used to denote the behavior of the error. For example, code 301 indicates a loading error for image. You can refer to documentation [Error Codes](/api/errors/error-code.md) to learn the specific behavior each error code represents.

#### getSubcode

```java
public int getSubcode()
```

Return the error subcode. The error subcode is a 5 to 6-digit number derived from extending the error code by 2 digits. The error subcode is used to indicate the cause of the error. For example, subcode 30101 indicates that the loaded image is too large. You can refer to documentation [Error Codes](/api/errors/error-code.md) to learn the specific cause each error subcode represents.

#### isFatal

```java
public boolean isFatal()
```

Determine if the error level is `Fatal`. `LynxError` has three levels: `Fatal`, `Error`, and `Warn`. `Fatal` indicates a critical error that might cause the Lynx page to go blank, requiring the integrator to perform fallback handling; for example, attempting to reload the Lynx page or displaying an error page. `Error` denotes a non-critical error that might cause some functionalities of the Lynx page to become unavailable. `Warn` signifies a warning error that does not affect the functionality of the Lynx page but should be addressed if possible. You can refer to documentation [Error Codes](/api/errors/error-code.md) to learn about the error levels associated with each subcode. If the level is `Undecided`, it means that the error level for that subcode is determined at runtime.

#### getMsg

```java
public boolean getMsg()
```

Return all error information in JSON string format, including the code, subcode, error message, level, and fix suggestion.

## iOS

#### errorCode

```objective-c
- (NSInteger)errorCode
```

Return the error code. The error code is a 3 to 4-digit number used to denote the behavior of the error. For example, code 301 indicates a loading error for image. You can refer to documentation [Error Codes](/api/errors/error-code.md) to learn the specific behavior each error code represents.

#### subcode

```objective-c
- (NSInteger)subcode
```

Return the error subcode. The error subcode is a 5 to 6-digit number derived from extending the error code by 2 digits. The error subcode is used to indicate the cause of the error. For example, subcode 30101 indicates that the loaded image is too large. You can refer to documentation [Error Codes](/api/errors/error-code.md) to learn the specific cause each error subcode represents.

#### isFatal

```objective-c
- (BOOL)isFatal
```

Determine if the error level is `Fatal`. `LynxError` has three levels: `Fatal`, `Error`, and `Warn`. `Fatal` indicates a critical error that might cause the Lynx page to go blank, requiring the integrator to perform fallback handling; for example, attempting to reload the Lynx page or displaying an error page. `Error` denotes a non-critical error that might cause some functionalities of the Lynx page to become unavailable. `Warn` signifies a warning error that does not affect the functionality of the Lynx page but should be addressed if possible. You can refer to documentation [Error Codes](/api/errors/error-code.md) to learn about the error levels associated with each subcode. If the level is `Undecided`, it means that the error level for that subcode is determined at runtime.

#### userInfo

```objective-c
- (NSDictionary*)userInfo
```

Return an `NSDictionary` from which the error information can be queried using the key `LynxErrorUserInfoKeyMessage`. The error information is a JSON string that includes the code, subcode, error message, level, fix suggestion, etc.

## Compatibility




---
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`&#x20;

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`&#x20;

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`&#x20;

Description: Failed to fetch app bundle by provider\
FixSuggestion: Please check if the app bundle is available

### 10204: `E_APP_BUNDLE_LOAD_PARSE_FAILED`&#x20;

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`&#x20;

Description: A bad TemplateBundle is provided\
FixSuggestion: Please check the error message of the bundle

### 10299: `E_APP_BUNDLE_LOAD_EXCEPTION`&#x20;

Description: Exception occurred while rendering app bundle

## 105: `EB_APP_BUNDLE_RELOAD` \{#105}

### 10501: `E_APP_BUNDLE_RELOAD_EARLY_RELOAD`&#x20;

Description: `reloadTemplate` before `loadTemplate`\
FixSuggestion: Please `loadTemplate` before `reloadTemplate`

## 201: `EB_BTS_RUNTIME_ERROR` \{#201}

### 20100: `E_BTS_RUNTIME_ERROR`&#x20;

Description: Runtime error for an unspecified reason

### 20101: `E_BTS_RUNTIME_ERROR_SCRIPT_ERROR`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

Description: Network or other issues\
FixSuggestion: Please investigate the corresponding image download workflow for potential issues

### 30199: `E_RESOURCE_IMAGE_EXCEPTION`&#x20;

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`&#x20;

Description: Failed to process font resource

### 30201: `E_RESOURCE_FONT_SRC_FORMAT_ERROR`&#x20;

Description: Font src format error\
FixSuggestion: Please check the font-face format

### 30202: `E_RESOURCE_FONT_RESOURCE_LOAD_ERROR`&#x20;

Description: Failed to load font resource\
FixSuggestion: Please check whether font resource is available

### 30203: `E_RESOURCE_FONT_BASE64_PARSING_ERROR`&#x20;

Description: Failed to parse base64 resource\
FixSuggestion: Please check whether the base64 resource is available

### 30204: `E_RESOURCE_FONT_FILE_FORMAT_NOT_SUPPORTED`&#x20;

Description: Font file format is not supported\
FixSuggestion: Please use a font file in ttf or otf format

### 30205: `E_RESOURCE_FONT_REGISTER_FAILED`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

Description: i18n Resource Error

## 321: `EB_RESOURCE_MODULE` \{#321}

### 32101: `E_RESOURCE_MODULE_PARAMS_ERROR`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

Description: Invalid data type\
FixSuggestion: Target string data should be enabled to be parsed into a table

### 40199: `E_DATA_FLOW_UPDATE_EXCEPTION`&#x20;

Description: Exception occurred while updating data

## 501: `EB_ELEMENT_API` \{#501}

### 50101: `E_ELEMENT_API_FATAL`&#x20;

Description: Fatal error in element API. Please find detailed information in the context

### 50102: `E_ELEMENT_API_ERROR`&#x20;

Description: Error in element API. Please find detailed information in the context

## 502: `EB_ELEMENT_UPDATE` \{#502}

### 50201: `E_ELEMENT_UPDATE_NODE_IS_NULL`&#x20;

Description: Element update error for an unspecified reason

## 601: `EB_LAYOUT_INTERNAL` \{#601}

### 60100: `E_LAYOUT_INTERNAL`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

Description: Main thread script error for an unspecified reason

## 1111: `EB_MTS_RENDERER_FUNCTION` \{#1111}

### 111101: `E_MTS_RENDERER_FUNCTION_FATAL`&#x20;

Description: Fatal error during rendering. Please find detailed information in the context

### 111102: `E_MTS_RENDERER_FUNCTION_ERROR`&#x20;

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`&#x20;

Description: Please ensure that `destroy` is called on UI thread

### 120202: `E_THREAD_WRONG_THREAD_SYNC_FLUSH_ERROR`&#x20;

Description: Please ensure that `SyncFlush` is called on UI thread

## 1301: `EB_CSS` \{#1301}

### 130100: `E_CSS`&#x20;

Description: CSS error for an unspecified reason

### 130101: `E_CSS_UNKNOWN_PROPERTY`&#x20;

Description: Unknown CSS property id

### 130102: `E_CSS_UNSUPPORTED_VALUE`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

Description: Property is not inheritable\
FixSuggestion: Remove property name from inheritance list

## 1303: `EB_CSS_PARSER` \{#1303}

### 130300: `E_CSS_PARSER`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

Description: Invoke function with wrong parameter

## 2201: `EB_COMPONENT_API` \{#2201}

### 220101: `E_COMPONENT_API_DEPRECATED`&#x20;

Description: A deprecated component API is invoked

## 2202: `EB_COMPONENT_LIST` \{#2202}

### 220201: `E_COMPONENT_LIST_ILLEGAL_ITEM_KEY`&#x20;

Description: Error for illegal list item-key\
FixSuggestion: Please check the legality of the item-key

### 220202: `E_COMPONENT_LIST_DUPLICATED_CELL`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

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`&#x20;

Description: Multi thread strategy can not be used by default\
FixSuggestion: Please set the attribute enable-async-list of  to true

### 220208: `E_COMPONENT_LIST_DUPLICATE_ITEM_KEY`&#x20;

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`&#x20;

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`&#x20;

Description: An error occurs in an customized element

## 9901: `EB_EXCEPTION_PLATFORM` \{#9901}

### 990100: `E_EXCEPTION_PLATFORM`&#x20;

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`&#x20;

Description: JNI exceptions for an unspecified reason\
FixSuggestion: This error is caught by Lynx engine. Please file an issue to Lynx for help



---
url: /blog/index.md
---

# Lynx Blog

Check here for the latest articles and release announcements about Lynx.

## [What’s new in Lynx 3.2](/blog/lynx-3-2.md)

*May 14th, 2025 by [Wentao Shi](https://github.com/toretto-wt), representing [The Lynx Team](https://x.com/lynxjs_org)*

Lynx 3.2 delivers updates across its framework, engine, and tools, including the ReactLynx testing tools, `llms.txt` support, new Grid Layout features, improvements to `<list>` and `<text>`, and more.

## [Lynx Roadmap 2025](/blog/lynx-open-source-roadmap-2025.md)

*March 20th, 2025 by [Shouqun Liu](https://github.com/Shouqun)*

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

## [Lynx: Unlock Native for More](/blog/lynx-unlock-native-for-more.md)

*March 5th, 2025 by [Xuan Huang](https://x.com/huxpro), representing [The Lynx Team](https://x.com/lynxjs_org)*

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

***



---
url: /blog/lynx-3-2.md
---



*May 14th, 2025*

# What’s new in Lynx 3.2

![lynx-in-3-2](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/lynx-3-2.png)

Today, I'm pleased to share that Lynx 3.2, the first version of Lynx since we [open-sourced](/blog/lynx-unlock-native-for-more.md) it in March 2025, is now stable!

Lynx 3.2 delivers updates across its framework, engine, and tools, including the [ReactLynx testing tools](#reactlynx-testing-library), [`llms.txt` support](#websitellmstxt-support), [new Grid Layout features](#css-grid-layoutminmaxmax-contentfit-content), improvements to [`<list>`](#improvements-tolist) and [`<text>`](#text-can-be-customized-to-select-across-multiple-elements), and more, to bring you more familiar development experience and more capabilities. With over [296 commits](https://github.com/lynx-family/lynx/releases/) from 61 contributors (including some first-time contributors). Let’s explore what’s new!

## ReactLynx Testing Library

[Testing Library](https://testing-library.com/) is a popular way in the JavaScript community to test UI components, and we've adapted it for Lynx. We now introduce a new package [`@lynx-js/react/testing-library/`](/api/reactlynx-testing-library/index.md) to provide testing abstractions such as [`render`](/api/reactlynx-testing-library/Function.render.md). It can also be used with the official [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) to assert the presence and behavior of elements using matchers such as [`toBeInTheDocument`](https://github.com/testing-library/jest-dom?tab=readme-ov-file#tobeinthedocument).

```js
import '@testing-library/jest-dom';
import { expect, it } from 'vitest';
import { render } from '@lynx-js/react/testing-library';

it('renders', () => {
  const Wrapper = ({ children }) => (
    <view data-testid="wrapper">{children}</view>
  );
  const Comp = () => (
    <view data-testid="inner" style="background-color: yellow;" />
  );
  const { container, getByTestId } = render(<Comp />, { wrapper: Wrapper });

  expect(getByTestId('wrapper')).toBeInTheDocument();
  expect(container.firstChild).toMatchInlineSnapshot(`
    <view data-testid="wrapper">
      <view data-testid="inner" style="background-color: yellow;"/>
    </view>
  `);
});
```

[Learn more about how to use ReactLynx Testing Library here.](/react/reactlynx-testing-library.md)

## Website: `llms.txt` Support

By upgrading to [Rspress v2](https://v2.rspress.dev/) and taking advantage of the new [LLM plugin](https://x.com/rspack_dev/status/1917844832149725695), the Lynx website is now fully equipped with [https://lynxjs.org/llms.txt](https://lynxjs.org/llms.txt) and [https://lynxjs.org/llms-full.txt](https://lynxjs.org/llms-full.txt) to help with AI understanding and improve your experience vibe-coding with Lynx. For every page you can get the original markdown by replacing the .html extension with .md.

[Learn more about what is `llms.txt`](https://llmstxt.org/).

## CSS Grid Layout: `minmax()`, `max-content`, `fit-content` Web-friendly

Lynx 3.2 adds three CSS functions `minmax()`, `max-content`, and `fit-content`, to help you better controll grid sizes in the [CSS Grid Layout](https://lynxjs.org/guide/ui/layout/grid-layout.html). 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

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

[Learn more about implementing Pagination with `item-snap`.](/api/elements/built-in/list.md#pagination-withitem-snap)

### `z-index` Support in `<list-item>` Web-friendly

Lynx 3.2 supports [**z-index**](https://lynxjs.org/zh/api/css/properties/z-index.html) on `<list-item>`, allowing for more flexible adjustment of the view hierarchy of list items.

## `<text>` Can Be Customized to Select Across Multiple Elements Web-friendly

In long article scenarios, with the newly added [`custom-text-selection`](/api/elements/built-in/text.md#custom-text-selection) attribute, you can now [implement customized logic](/api/elements/built-in/text.md#crosstext-selection-and-copying) to select and copy text across text elements, making the text selection experience more similar to the Web.

## Microtasks Web-friendly

Before Lynx 3.2, Lynx did not support micro-task. The behavior of the following code is inconsistent with that in web browsers. In Lynx 3.2, `Promise` based on microtasks is implemented, and a new API [`lynx.queueMicrotask`](/api/lynx-api/lynx/lynx-queue-microtask.md) is delivered.

```js
setTimeout(() => {
  console.log('this is a timeout, will exec after');
}, 0);

Promise.resolve().then((value) => {
  console.log('this is a Promise, will exec before');
});
```

| Results in Lynx before 3.2                                                                                               | Results in Chrome                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/lynx-test-result.png) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/chrome-test-result.png) |

## More `console` APIs Web-friendly

Lynx 3.2 further implements most of the [W3C-compliant](https://developer.mozilla.org/en-US/docs/Web/API/console) `console` APIs to provide a more comprehensive debugging experience. See the [API Reference](/api/lynx-api/global/console/assert.md) for more details.

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

## Upgrade to Lynx 3.2

### Android

Please refer to the [integrate-with-existing-apps](https://lynxjs.org/guide/start/integrate-with-existing-apps.html#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:

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

```groovy title=build.gradle.kts {3-6}
dependencies {
    // lynx dependencies
    implementation("org.lynxsdk.lynx:lynx:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-jssdk:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-trace:3.2.0")
    implementation("org.lynxsdk.lynx:primjs:2.12.0")
}
```

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

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

}
```

```groovy title=build.gradle.kts {8-24}
dependencies {
    // lynx dependencies
    implementation("org.lynxsdk.lynx:lynx:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-jssdk:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-trace:3.2.0")
    implementation("org.lynxsdk.lynx:primjs:2.12.0")

    // integrating image-service
    implementation("org.lynxsdk.lynx:lynx-service-image:3.2.0-")

    // image-service dependencies, if not added, images cannot be loaded; if the host APP needs to use other image libraries, you can customize the image-service and remove this dependency
    implementation("com.facebook.fresco:fresco:2.3.0")
    implementation("com.facebook.fresco:animated-gif:2.3.0")
    implementation("com.facebook.fresco:animated-webp:2.3.0")
    implementation("com.facebook.fresco:webpsupport:2.3.0")
    implementation("com.facebook.fresco:animated-base:2.3.0")

    // integrating log-service
    implementation("org.lynxsdk.lynx:lynx-service-log:3.2.0")

    // integrating http-service
    implementation("org.lynxsdk.lynx:lynx-service-http:3.2.0")

    implementation("com.squareup.okhttp3:okhttp:4.9.0")
}
```

### iOS

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

```ruby title="Podfile" {1,6-8,10}
source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
pod 'Lynx', '3.2.0', :subspecs => [
'Framework',
]

pod 'PrimJS', '2.12.0', :subspecs => ['quickjs', 'napi']
end
```

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

```ruby title="Podfile" {8-13,15-17}
source 'https://cdn.cocoapods.org/'
platform :ios, '10.0'
target 'YourTarget' do
  pod 'Lynx', '3.2.0', :subspecs => [
    'Framework',
  ]
  pod 'PrimJS', '2.12.0', :subspecs => ['quickjs', 'napi']
  # integrate image-service, log-service, and http-service
  pod 'LynxService', '3.2.0', :subspecs => [
      'Image',
      'Log',
      'Http',
  ]

  # ImageService
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'

end
```

## Final Words

Thanks to Lynx community for making this release possible! As a newly open-source project, we're thrilled about our future and we can’t wait to see the use of Lynx in your apps.

In the future, we will gradually introduce more feature support as our [roadmap](https://lynxjs.org/blog/lynx-open-source-roadmap-2025.html). We'll add new components like `<Input>` and adapt to more platforms such as HarmonyOS and PC.

Please check the [release notes and changelog](https://github.com/lynx-family/lynx/releases/tag/3.2.0), and let’s embark on a new adventure!

***

*Thanks to [Xuan Huang](https://x.com/huxpro), [Ray Zhang](https://x.com/zoolsher), and [Shouqun Liu](https://x.com/liushouqun) for their contributions in creating this blog post.*



---
url: /blog/lynx-open-source-roadmap-2025.md
---



*March 19th, 2025*

# Lynx Roadmap 2025

[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).
Additionally, the website's repository is open-sourced (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](https://lynxjs.org/guide/spec.html#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

Today, we're excited to introduce **Lynx**, a *family* of technologies empowering developers to use their existing web skills to create truly native UIs for both mobile and web from a single codebase. Designed for diverse use cases and rich interactivity, Lynx delivers vibrant and engaging UIs for large-scale apps like TikTok, featuring a speedy, versatile rendering engine, performance-driven dual-threaded UI programming, modern Rust-based tooling, and more!

We deeply appreciate all the prior arts that have shaped the field of cross-platform development, and aspire to contribute to this movement by **open sourcing** Lynx today, inviting more developers to build applications with more freedom and productivity.

## Ship Native at Scale and Velocity

For the generation of digital natives, mobile phones—and the apps on them—are their first digital experiences. For these app-centric users, a non-native experience isn't just inconvenient; it's a red flag. A blank screen, a 0.1s lag in a "like" animation, or an unfamiliar UI pattern can make an interface feel "cheap" or untrustworthy. We believe that native primitives and responsiveness aren't just nice-to-haves—***native is a necessity***.

Despite the rapid growth of the app economy, delivering such experiences at *scale* and *velocity* remains to be a challenge. The growing diversity of form factors and platforms forces developers to rebuild the same experiences multiple times, leading to wasted effort, siloed teams, and delayed time-to-market. We believe that by enabling developers to build once and reach more platforms, *we can deliver joys **for more users, faster***.

TikTok, known and loved as a mobile-first platform, continuously brings innovative and engaging experiences to diverse and dynamic users around the world. To meet these demands, it gradually adopted Lynx and has increasingly bet on it. Today, Lynx powers an extremely wide spectrum of surfaces—from the lightweight, high-frequency **Search** panel to full-fledged [TikTok Studio](https://support.tiktok.com/en/using-tiktok/creating-videos/tiktok-studio) app; from complex e-commerce storefronts like **Shop** that demand reliability and trust, to highly engaging experiences like **LIVE**, as well as powering high-profile events and cultural moments such as [Disney100 on TikTok](https://newsroom.tiktok.com/en-us/disney-100) and [The Met Gala on TikTok](https://newsroom.tiktok.com/en-us/tiktok-goes-to-the-met-gala).

![lynx-in-tiktok](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-in-tiktok.jpg)

TikTok's extensive use of Lynx

We believe *scale* and *velocity* mean more than just applying a feature, bug fix, or optimization across all platforms to improve cost efficiency. It also means the *versatility* to adapt the same shared technological foundation to a broad spectrum of scenarios—without the need to build new teams or reinvent the wheel for every unique use case.

## Inspire and Enrich the Web community

The web platform was historically created for [documents](https://www.w3.org/People/Berners-Lee/WorldWideWeb.html) and then [gradually](https://extensiblewebmanifesto.org/#signatories) [evolved](https://infrequently.org/2015/06/progressive-apps-escaping-tabs-without-losing-our-soul/) into a development platform. Yet, it continues to [face constraints](https://infrequently.org/2020/06/platform-adjacency-theory/) that slow down its ability to adapt and innovate quickly. Therefore, shaping the web technologies for cross-platform development has become a defining norm in the industry. Since 2008, PhoneGap (later [Cordova](https://cordova.apache.org/)) [strived to keep the Web as cross-platform solution](https://web.archive.org/web/20161210233245/http://phonegap.com/blog/2012/05/09/phonegap-beliefs-goals-and-philosophy/) by augmenting Webview with native capabilities. In 2015, [React Native pioneered bridging native UI with web technologies](https://reactnative.dev/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile), enabling declarative UI with React.js on mobile. That same year, [Flutter](https://developers.googleblog.com/en/flutter-10-googles-portable-ui-toolkit/), with its web heritage, adopted a similar declarative UI model and introduced a new approach using a custom rendering engine.

Lynx followed a similar spirit—you can think of it as an ***"alternative Web tailored for app development*"**. It aims to honor the assets of web technologies while taking an opinionated approach, supporting web-like APIs and adding constraints and extensions with clear intent.

To illustrate this balance, let me share two examples: one where we choose to follow the web and another where we intentionally make a difference.

### Craft Designs with Markups and CSS as Usual

At its core, UI technologies exist to deliver exceptional product design. Lynx embraces the familiarity of web development, allowing developers to write markup and CSS just as they would for the web. Lynx natively supports [CSS animations and transitions](/guide/styling/animation.md), [CSS selectors and variables for theming](/guide/styling/custom-theming.md), and modern CSS visual effects like [gradients](/guide/styling/appearance.md#gradient), [clipping, and masking](/guide/styling/appearance.md#clipping-and-masking)—all designed to unlock the creativity of the web community to achieve trending *design engineering*.

Using mask-image to create a circle area with fading edge

### Use the Main Thread Responsibly for Interactivity

One of Lynx's most notable architectural decisions is its **statically-enforced division** of user scripting into two distinct runtimes: a *[main-thread](/guide/spec.md#main-thread-or-lynx-main-thread) runtime*, powered by [**PrimJS**](https://github.com/lynx-family/primjs), a custom JavaScript engine specifically optimized for Lynx, dedicated to privileged, synchronous UI tasks like initial launch and high-priority event handling, and a *[background](/guide/spec.md#background-thread-aka-off-main-thread) runtime* as the default for user code, ensuring the main thread remains low workload and *non-blocking*. This enables two killer features of Lynx:

1. [*Instant First-Frame Rendering (IFR)*](/guide/interaction/ifr.md): Backed by [usability research](https://www.nngroup.com/articles/response-times-3-important-limits/), if rendering is fast enough—and Lynx is—no special intermediate feedback is needed. By briefly blocking the main thread until the first frame is fully rendered, Lynx eliminates blank screens, creating a perceived instant experience.

2. [*Main-Thread Scripting (MTS)*](/react/main-thread-script.md): A small, statically scheduled piece of code, privileged to run on the main thread, handles high-priority events and gestures—making it ideal for implementing silky-smooth, highly responsive interfaces that feels native.

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!

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: /index.md
---




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

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



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

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




---
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](/en/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](/en/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).

Lynx does not have a complete corresponding API for methods such as `e.stopPropagation()` and `e.preventDefault()` that are commonly used on the Web. But Lynx's [Event Propagation Mechanism](/guide/interaction/event-handling/event-propagation.md) allows you to implement similar functions or effects as on the Web.

```diff
- <button onTouchStart={...} />
+ <view bindtouchstart={...} catchtouchstart={...}/>
```

### No `document` and `window`

Lynx does not yet provide `document` and `window` objects, so ReactLynx does not support these two objects either.

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](/en/react/main-thread-script.md),
which are generally used to help developers maintain a near-native user experience when implementing some complex interactions.

This means that you cannot use any libraries that depend on `document` or `window`.

There are basically two ways for this difference:

* Most of the time, Lynx provides the feature with a different API. For example, you can use the APIs under the `lynx` object like [`lynx.reload`](/api/lynx-api/lynx/lynx-reload.md) to replace `window.location.reload()`.
* Occasionally, Lynx does not provide the feature. You can use Lynx's [NativeModules](/guide/use-native-modules.md) and [Custom Elements](/guide/custom-native-component.md) to extend Lynx's capabilities.

## Next Steps

### Further Learning ReactLynx

### Learn Lynx Basics

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



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

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

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

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

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

1. Card Details
   * The card can perform flip animation
   * Here we'll learn how to use CSS animations to create smooth flip effects

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

3. The top amount display and bottom buttons, these components are relatively simple, we'll implement them using the [view](/api/elements/built-in/view.md) element.

Let's focus on three technical points: building an interactive scrolling list, implementing 3D flip animation effects, and passing data between components.

### Building an Interactive Card List

First, let's create a bank card list. This list needs to display basic information for each card, including:

* Bank type (like Bac, Boc, etc.)
* Card number (showing first and last four digits)
* Cardholder name
* Whether it's a primary card

Let's organize this information into a data structure:

```tsx title="BankCardScrollView.tsx"
export interface BankCard {
  type: string; // Bank type (like Bac, Boc, etc.)
  number: string; // Card number
  name: string; // Cardholder name
}
```

Then, prepare some card data for display:

```tsx title="BankCardScrollView.tsx"
const cards = [
  { type: "bac", number: "4558 **** **** 6767", name: "Alex Quentin" },
  { type: "boc", number: "6222 **** **** 8058", name: "Alex Quentin" },
  ...
];
```

Next, let's use the `<scroll-view>` element to create a vertically scrollable list to display all card information:

```tsx title="BankCardScrollView.tsx" {6}
export default function BankCardScrollView() {
  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

To let users know which card they've selected, we need to add an icon to indicate selection:

```scss title="BankCardScrollView.tsx"
<image className="check-icon" src={checkIcon} />
```

Then, we need to define a `selectedCard` state to track the currently selected card:

```tsx title="BankCardScrollView.tsx"
const [selectedCard, setSelectedCard] = useState(cards[0]);
```

After that, we need to add a `handleCardSelect` function in the `<BankCardScrollView>` component to handle card selection events:

```tsx title="BankCardScrollView.tsx"
const handleCardSelect = (card: BankCard) => {
  setSelectedCard(card);
};
```

When a user clicks a card, it will trigger the `handleCardSelect` function, which will update the `selectedCard` state:

```tsx title="BankCardScrollView.tsx" {3}
<view
  className={`card ${selectedCard === card ? 'selected' : ''}`}
  bindtap={() => handleCardSelect(card)}
>
  ...
</view>
```

Let's combine the above logic. When a user selects a card, it will show a small check mark on the right to indicate the current selection:

```tsx title="BankCardScrollView.tsx {5,17}"
export default function BankCardScrollView() {
  const [selectedCard, setSelectedCard] = useState(cards[0]);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
  };

  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
              {selectedCard === card && (
                <image className="check-icon" src={checkIcon} />
              )}
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

Now, we've completed building this interactive card list. Let's see how it works!

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

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

We'll add the top amount display, and we're done!

## 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/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](https://lynxjs.org/api/engine/element-api), 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](/en/react/thinking-in-reactlynx.md#your-code-runs-on-two-threads)

In the second parameter [`RenderOptions`](/en/api/reactlynx-testing-library/Interface.RenderOptions.md) of the [`render`](/en/api/reactlynx-testing-library/Function.render.md) method, there are two options [`enableMainThread`](/en/api/reactlynx-testing-library/Interface.RenderOptions.md#enablemainthread) and [`enableBackgroundThread`](/en/api/reactlynx-testing-library/Interface.RenderOptions.md#enablebackgroundthread). `enableMainThread` is used to enable [IFR](/en/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.md
---



# Routing

## Using `react-router`

React Router enables "single page routing".

### Installation

Since ReactLynx only have React v17 API now, you should install `react-router` v6.

### 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/state-management/jotai.md
---



# Jotai

## Using `jotai`

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

### Installation

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

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

### 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](/en/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.

The reason relates to Lynx's dual-threaded runtime architecture, where the code for `<EventListenerComponent />` executes on both threads:

* On the background thread:

  The `lynx.getJSModule` function is available as part of the Lynx `GlobalEventEmitter` API. Therefore, executing `lynx.getJSModule('GlobalEventEmitter')` works without issues.

* On the main thread:

  The `getJSModule` function does not exist on the main thread. Thus, when this code executes on the main thread, `lynx.getJSModule` is evaluated as `undefined`, leading to the "not a function" error.

## Some code can only run on the background thread

Typically, side effects unrelated to rendering cannot be executed on the main thread, such as data updates, event listeners, timers, and network requests.
Executing these side effects on the main thread will result in runtime errors.
We call code that only executes on the background thread **background only** code.
By marking background only code, we help the compiler optimize code and prevent these side effects from executing on the main thread.

There are three key rules for background only code:

1. [Rule 1: Code that meets any of these conditions is considered background only](#rule-1).
2. [Rule 2: Background only code can only be used within other background only code](#rule-2).
3. [Rule 3: Code that is only used by background only code is considered background only](#rule-3).

### Rule 1: Code that meets any of these conditions is considered background only \{#rule-1}

Lynx considers code that meets any of these conditions as background only:

1. Event handlers (e.g. `bindtap` / `catchtap`)
2. Effects (e.g. `useEffect` / `useLayoutEffect`)
3. `ref` prop and `useImperativeHandle`
4. Functions with [`'background only'`] directive
5. Modules with `import 'background-only'` directive

For example, all these functions with `console.log` in the following example are considered background only. These functions will neither be bundled into main thread code nor executed on the main thread.

```jsx
import { useEffect } from '@lynx-js/react';

function App() {
  useEffect(() => console.log('Effect is background only'));
  return (
    <view bindtap={(e) => console.log('Event is background only')}>
      <text ref={(ref) => console.log('Ref is background only')}>
        Hello, ReactLynx!
      </text>
    </view>
  );
}

function backgroundOnly() {
  'background only';
  console.log('Directive marked function is background only');
}
```

```js
import 'background-only';

export const env = NativeModules.env;
console.log('Directive marked module is background only');
```

Following this rule, we can see that the earlier `<EventListenerComponent />` should move its `GlobalEventEmitter` usage into `useEffect`.
This ensures this code only runs on the background thread where the `GlobalEventEmitter` API is available:

```js
import { useEffect } from '@lynx-js/react';

const EventListenerComponent = () => {
  useEffect(() => {
    lynx.getJSModule('GlobalEventEmitter').addListener('myHappyEvent', () => {
      console.log('myHappyEvent triggered!');
    });
  }, []);
  return <text>Hello</text>;
};
```

### Rule 2: Background only code can only be used within other background only code \{#rule-2}

When **dependencies** are involved, things become more complicated.
Simply put, background only code can only be called by other background only code.

```jsx
import { backgroundOnlyFunction } from 'external-module';

backgroundOnlyFunction(); // ❌ Error: calling background only at top level

export function App() {
  function backgroundOnly() {
    'background only';
    fetch();
    NativeModules.call();
    backgroundOnlyFunction(); // ✅ Correct: calling background only API inside background only function
  }

  backgroundOnly(); // ❌ Error: calling background only code in render function

  useEffect(() => {
    backgroundOnly(); // ✅ Correct: calling background only code from background only code
  }, []);

  return <view />;
}
```

### Rule 3: Code that is only used by background only code is considered background only \{#rule-3}

Usually, event callbacks of elements are considered background only. `handleTap` doesn't need the `'background only'` directive but will be considered background only code because it's only used as a handler in the `bindtap` event.

```jsx
function App() {
  function handleTap() {
    // No need to mark this function since `bindtap` is considered background only
  }
  return <view bindtap={handleTap} />;
}
```

The `backgroundOnly` function will also be considered background only because it's only called in the `useEffect` callback.

```jsx
function App() {
  function backgroundOnly() {
    // No need to mark this function
    // since `useEffect` is considered background only
    // `backgroundOnly` will be identified as unused and removed by the optimizer
  }
  useEffect(() => {
    backgroundOnly();
  });
  return <view />;
}
```

#### Exceptions

Due to limitations in compiler analysis capabilities and compile-time performance, there are some exceptions to this rule. We will work to address these issues in future versions.

When event handlers are passed as props, you must add the [`'background only'`] directive. Otherwise, the compiler cannot identify `handleTap` as background only code and will include it in the main thread bundle:

```jsx
function App() {
  function handleTap() {
    'background only';
    // Unfortunately, you must mark event callbacks here
  }
  return <Button onClick={handleTap} />;
}

function Button({ onClick }) {
  return <view bindtap={onClick} />;
}
```

When using custom Hooks, you must add the [`'background only'`] directive. Otherwise, `backgroundOnly` will be treated as non-background only code and included in the main thread bundle.
This occurs because the compiler cannot determine if the callback of `useMount` is only used in background only code.

```jsx
function useMount(effect) {
  useEffect(() => {
    effect();
  }, []);
}

function App() {
  function backgroundOnly() {
    // No need to mark this function
    // since `backgroundOnly` is only used in `useMount` callback
  }
  useMount(() => {
    'background only';
    // You need to mark this function
    backgroundOnly();
  });
  return <view />;
}
```

[`'background only'`]: /en/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](/en/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
[`output.assetPrefix`]: ../../api/rspeedy/rspeedy.output.assetprefix
[`output.dataUriLimit`]: ../../api/rspeedy/rspeedy.output.dataurilimit
[`tools.rspack`]: ../../api/rspeedy/rspeedy.tools.rspack
[`source.assetsInclude`]: ../../api/rspeedy/rspeedy.source.assetsinclude



---
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](/en/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
1. Node.js >= v22.6 with [--experimental-strip-types](https://nodejs.org/api/cli.html#--experimental-strip-types)
1. 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]

Options:
  -b --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
  --environment <name...>   specify the name of environment to build
  -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]

Options:
  -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
  --environment <name...>   specify the name of environment to build
  -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]

Options:
  -b --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
  -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:
  --mode <mode>         specify the mode of Rsbuild (default: "development")
  --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
  -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 `--env 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
[`output.filename.js`]: /api/rspeedy/rspeedy.filename.js
[`output.filename.bundle`]: /api/rspeedy/rspeedy.filename.bundle
[`output.distPath`]: /api/rspeedy/rspeedy.output.distpath
[`output.distPath.js`]: /api/rspeedy/rspeedy.distpath.js
[`output.legalComments`]: /api/rspeedy/rspeedy.output.legalcomments
[`output.sourceMap`]: /api/rspeedy/rspeedy.output.sourcemap



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

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



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

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

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

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

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

Since Rsbuild supports Tailwind CSS out of the box, you can directly refer to the guide on Rsbuild: [Use Tailwind CSS v3](https://rsbuild.dev/guide/basic/tailwindcss-v3).

After setting up Tailwind CSS, 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.

1. Install the `@lynx-js/tailwind-preset` package:

2) Add the `@lynx-js/tailwind-preset` to `tailwind.config.js`:

```js title=tailwind.config.js
import preset from '@lynx-js/tailwind-preset';

export default {
  presets: [preset],
};
```

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

:::

See the basic ReactLynx Tailwind CSS example at: https://github.com/lynx-family/lynx-examples/tree/main/examples/tailwindcss.



---
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) 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](./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.mdx)
- [`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.mdx).

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

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

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

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

```bash
npx upgrade-rspeedy@latest
```

### Upgrade to a specific version

To upgrade `@lynx-js/rspeedy` and its plugins to a specific version, use the following command in your project:

```bash
# Replace the `0.8.3` with the one you would like to install.
npx upgrade-rspeedy@0.8.3
```

### 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.3.0-next-20240823-28a1e571` 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:

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

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

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.

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

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.

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.

Scan the QR code to download the pre-built app from the [GitHub Release](https://github.com/lynx-family/lynx/releases/latest).

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

### Start developing

1. Navigate to the created project:

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

2. Install the NPM dependencies with package manager:

3) To start the development server, run:

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.

### 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/debugging/lynx-devtool.md), learn how to debug your Lynx app.

## Next steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

### Describing UI

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

### Integration

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



---
url: /react/start/integrate-with-existing-apps.md
---

import { PlatformTabs } from '@lynx';
import * as NextSteps from '@lynx/NextSteps';





# 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 hashKey="platform">
<PlatformTabs.Tab platform="ios">
### Integrate Lynx with Existing Apps (iOS)

import { Info, CodeFold } from '@lynx';
import { Steps } from '@theme';
import { Tab, Tabs } from 'rspress/theme';

<Info title="Lynx for iOS">
  - This article assumes that you are familiar with the basic concepts of native iOS application development.
  - You can refer to the project: [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/release/3.1) for all the code mentioned below.
</Info>

## 1. Dependency configuration

Using [Cocoapods](https://cocoapods.org/) can easily integrate Lynx into your application

<Info title="Recommended Versions">

- Cocoapods: >= 1.11.3
- Ruby: >= 2.6.10

</Info>

<Steps>

### Configuring Deps

1. **Lynx**

The core capabilities of [Lynx Engine](/guide/spec.html#engine) include basic capabilities such as parsing [Bundle](/guide/spec.html#lynx-bundle-or-bundle), style parsing, layout, and rendering views

Get the latest version of Lynx from Cocoapods. Then add Lynx to your Podfile:

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

2. **Lynx Service**

Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official. For example, `LynxImageService` is implemented using the [SDWebImage](https://github.com/SDWebImage/SDWebImage) image library by default. Apps that do not integrate SDWebImage components can rely on other image libraries to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;

Get the latest version of Lynx Service from Cocoapods. Then add Lynx Service to your Podfile:

<CodeFold height={360} toggle>

```ruby title="Podfile" {13-17,20-21}
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 dependencies:
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'
end
```

</CodeFold>

### Install Dependencies

Run `pod install` to install dependencies, then open your Xcode project. Additionally, make sure to disable the Sandbox Scripting capability.

:::note

In order to disable the **Sandbox scripting**, in Xcode click on your app, then on **build settings**. Filter for **script** and set the **User Script Sandboxing** to **NO**.

<img
  height="180px"
  width="640px"
  src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/integration_ios_warning.png"
/>
:::

</Steps>

## 2. Lynx Environment Initialization

<Steps>

### LynxEnv Initialization

LynxEnv provides a global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface call of the Lynx Engine.
For example, it can be initialized in `AppDelegate`

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">

```objective-c title=AppDelegate.m {6}
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxView.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [LynxEnv sharedInstance];
  return YES;
}
```

</Tab>
<Tab label="Swift">

```swift title=AppDelegate.swift {8}
import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    LynxEnv.sharedInstance()
    return true
  }
}

```
</Tab>
</Tabs>

</Steps>

## 3. Render LynxView

LynxView is the basic rendering unit provided by Lynx Engine. LynxView is an implementation inherited from iOS native [UIView](https://developer.apple.com/documentation/uikit/uiview). You can quickly construct a LynxView and add it to the [ViewController](https://developer.apple.com/documentation/uikit/uitab/viewcontroller/).

<Steps>


### Create Bundle Loader

Lynx Engine itself does not have the ability to load resources, so it is necessary to initialize LynxEnv, or when constructing [LynxView](/guide/spec.html#lynxview) to pass in the specific implementation of the `LynxTemplateProvider` protocol. Lynx will use the injected resource loader to obtain the Bundle content

You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.

1. First, please either generate the Bundle file from the [Quick Start](/guide/start/quick-start) phase or download the file below to your local machine, and then follow these steps to embed the file:

:::note
Bundle Example:
**https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle**
:::


:::note

Steps to embed files:
- In the target settings of the project, select the target;
- Select the **Build Phases** tab;
- In the **Copy Bundle Resources** section, click the add button (+) to add the file;

:::


2. Impl Bundle Loader

<Tabs groupId='integrating-lynx-with-existing-app-ios'>
<Tab label="Objective-C">

```objective-c title="DemoLynxProvider.h"
#import <Foundation/Foundation.h>
#import <Lynx/LynxTemplateProvider.h>

NS_ASSUME_NONNULL_BEGIN

@interface DemoLynxProvider : NSObject <LynxTemplateProvider>

@end

NS_ASSUME_NONNULL_END
```

</Tab>
<Tab label="Swift">

:::tip

Use [Bridging Header](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift) to import the required Lynx header files if you are using a Swift project, since Lynx is a project built with Objective-C.

:::

``` objective-c title="YourTarget-Bridging-Header.h"
#import <Lynx/LynxConfig.h>
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxTemplateProvider.h>
#import <Lynx/LynxView.h>
```

</Tab>
</Tabs>

<div style={{ marginBottom: 20 }} />

<Tabs groupId='integrating-lynx-with-existing-app-ios'>
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="DemoLynxProvider.m"
#import <Foundation/Foundation.h>

#import "DemoLynxProvider.h"

@implementation DemoLynxProvider

- (void)loadTemplateWithUrl:(NSString*)url onComplete:(LynxTemplateLoadBlock)callback {
    NSString *filePath = [[NSBundle mainBundle] pathForResource:url ofType:@"bundle"];
    if (filePath) {
      NSError *error;
      NSData *data = [NSData dataWithContentsOfFile:filePath options:0 error:&error];
      if (error) {
        NSLog(@"Error reading file: %@", error.localizedDescription);
        callback(nil, error);
      } else {
        callback(data, nil);
      }
    } else {
      NSError *urlError = [NSError errorWithDomain:@"com.lynx"
                                                  code:400
                                                userInfo:@{NSLocalizedDescriptionKey : @"Invalid URL."}];
      callback(nil, urlError);
    }
}

@end
```

</CodeFold>
</Tab>

<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="DemoLynxProvider.swift"
import Foundation

class DemoLynxProvider: NSObject, LynxTemplateProvider {
  func loadTemplate(withUrl url: String!, onComplete callback: LynxTemplateLoadBlock!) {
    if let filePath = Bundle.main.path(forResource: url, ofType: "bundle") {
      do {
        let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
        callback(data, nil)
      } catch {
        print("Error reading file: \(error.localizedDescription)")
        callback(nil, error)
      }
    } else {
      let urlError = NSError(domain: "com.lynx", code: 400, userInfo: [NSLocalizedDescriptionKey: "Invalid URL."])
      callback(nil, urlError)
    }
  }
}
```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Construct Basic LynxView

you may construct a basic LynxView as follows:

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {10-18}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
      builder.config = [[LynxConfig alloc] initWithProvider:[[DemoLynxProvider alloc] init]];
      builder.screenSize = self.view.frame.size;
      builder.fontScale = 1.0;
    }];
    lynxView.preferredLayoutWidth = self.view.frame.size.width;
    lynxView.preferredLayoutHeight = self.view.frame.size.height;
    lynxView.layoutWidthMode = LynxViewSizeModeExact;
    lynxView.layoutHeightMode = LynxViewSizeModeExact;
}
@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title=ViewController.swift {8-17}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    let lynxView = LynxView { builder in
      builder.config = LynxConfig(provider: DemoLynxProvider())
      builder.screenSize = self.view.frame.size
      builder.fontScale = 1.0
    }

    lynxView.preferredLayoutWidth = self.view.frame.size.width
    lynxView.preferredLayoutHeight = self.view.frame.size.height
    lynxView.layoutWidthMode = .exact
    lynxView.layoutHeightMode = .exact
  }
}
```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Add LynxView To The Window:

and then, adding the LynxView to the window.

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [self.view addSubview:lynxView];
}

@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    self.view.addSubview(lynxView)
  }
}

```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Render View

After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.loadTemplateFromURL` method to render the corresponding Bundle onto the LynxView.

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [lynxView loadTemplateFromURL:@"main.lynx" initData:nil];
}

@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    lynxView.loadTemplate(fromURL: "main.lynx", initData: nil)
  }
}

```

</CodeFold>
</Tab>
</Tabs>

Then you will see the following interface on the screen:

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-ios.png" width="200" />
</center>

</Steps>

Congratulations, you have now completed all the work of integrating Lynx Engine!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start) and [debugging](/guide/debugging/lynx-devtool) docs for in-depth insights on working with Lynx.

</PlatformTabs.Tab>

<PlatformTabs.Tab platform="android">
  ### Integrate Lynx with Existing Apps (Android)

import { Info, CodeFold } from '@lynx';
import { Steps } from '@theme';
import { Tab, Tabs } from 'rspress/theme';

<Info title="Lynx for Android">
  - This article assumes that you are familiar with the basic concepts of native Android application development.
  - You can refer to the project: [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/release/3.1) for all the code mentioned below.
</Info>

## 1. Dependency configuration

<Steps>

### Configuring Gradle

1. **Lynx**

The core capabilities of [Lynx Engine](/guide/spec.html#engine) include basic capabilities such as parsing [Bundle](/guide/spec.html#lynx-bundle-or-bundle), style parsing, layout, rendering views and the basic code of the javascript runtime that Lynx pages rely on

<Tabs groupId='integrating-lynx-with-existing-app-android-build'>
<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>

2. **Lynx Service**

Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official.For example, `LynxImageService` is implemented using the [Fresco](https://github.com/facebook/fresco) image library by default. Apps that do not integrate Fresco components can rely on other image libraries, such as [Glide](https://github.com/bumptech/glide) to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;

:::note
Since [Fresco](https://github.com/facebook/fresco) depends on [AndroidX](https://developer.android.com/jetpack/androidx), you also need to configure the following in gradle.properties:

```groovy
android.useAndroidX=true
```

:::

<Tabs groupId='integrating-lynx-with-existing-app-android-build'>
<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"

    implementation "com.squareup.okhttp3:okhttp:4.9.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"
}
```
</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>

<div style={{ marginBottom: 30 }} />

### Configure obfuscation rules ([Proguard](https://developer.android.com/build/shrink-code))

The obfuscation rules for` Lynx Engine` are as follows. It is recommended to refer to the latest source code configuration.

<CodeFold height={360} toggle>

```groovy title=proguard-rules.pro
# LYNX START
# use @Keep to annotate retained classes.
-dontwarn android.support.annotation.Keep
-keep @android.support.annotation.Keep class **
-keep @android.support.annotation.Keep class ** {
    @android.support.annotation.Keep <fields>;
    @android.support.annotation.Keep <methods>;
}
-dontwarn androidx.annotation.Keep
-keep @androidx.annotation.Keep class **
-keep @androidx.annotation.Keep class ** {
    @androidx.annotation.Keep <fields>;
    @androidx.annotation.Keep <methods>;
}

# native method call
-keepclasseswithmembers,includedescriptorclasses class * {
    native <methods>;
}
-keepclasseswithmembers class * {
    @com.lynx.tasm.base.CalledByNative <methods>;
}

# to customize a module, you need to keep the class name and the method annotated as LynxMethod.
-keepclasseswithmembers class * {
    @com.lynx.jsbridge.LynxMethod <methods>;
}

-keepclassmembers class *  {
    @com.lynx.tasm.behavior.LynxProp <methods>;
    @com.lynx.tasm.behavior.LynxPropGroup <methods>;
    @com.lynx.tasm.behavior.LynxUIMethod <methods>;
}

-keepclassmembers class com.lynx.tasm.behavior.ui.UIGroup {
    public boolean needCustomLayout();
}

# in case R8 compiler may remove mLoader in bytecode.
# as mLoader is not used in java and passed as a WeakRef in JNI.
-keepclassmembers class com.lynx.tasm.LynxTemplateRender {
    private com.lynx.tasm.core.LynxResourceLoader mLoader;
}

# the automatically generated setter classes use the class names of LynxBaseUI and ShadowNode and their subclasses.
-keep class com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class com.lynx.tasm.behavior.shadow.ShadowNode
-keep class com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class * extends com.lynx.tasm.behavior.shadow.ShadowNode
-keep class * extends com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.jsbridge.LynxContextModule
-keep class * implements com.lynx.tasm.behavior.utils.Settable
-keep class * implements com.lynx.tasm.behavior.utils.LynxUISetter
-keep class * implements com.lynx.tasm.behavior.utils.LynxUIMethodInvoker
-keep class com.lynx.tasm.rendernode.compat.**{
    *;
}
-keep class com.lynx.tasm.rendernode.compat.RenderNodeFactory{
    *;
}
# LYNX END
```

</CodeFold>

</Steps>

## 2. Environment Initialization

<Steps>

### Lynx Service Initialization

- Lynx Service provides host feature-related capabilities and it is recommended to complete the initialization of Lynx Service during the `Application#onCreate` lifecycle of the application.
- Lynx Service needs to be actively injected

:::tip

Please specify your custom Application class in the AndroidManifest.xml file, since Lynx needs to perform some global initialization operations when the application starts.

```xml title="/app/src/main/AndroidManifest.xml" {2}
<application
  android:name=".YourApplication">
</application>
```

:::

<Tabs groupId='integrating-lynx-with-existing-app-android'>
  <Tab label="Java">

<CodeFold height={360} toggle>
```java title=YourApplication.java {17,20-30}
import android.app.Application;

import com.facebook.drawee.backends.pipeline.Fresco;
import com.facebook.imagepipeline.core.ImagePipelineConfig;
import com.facebook.imagepipeline.memory.PoolConfig;
import com.facebook.imagepipeline.memory.PoolFactory;
import com.lynx.service.http.LynxHttpService;
import com.lynx.service.image.LynxImageService;
import com.lynx.service.log.LynxLogService;
import com.lynx.tasm.service.LynxServiceCenter;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
    }

    private void initLynxService() {
        // init Fresco which is needed by LynxImageService
        final PoolFactory factory = new PoolFactory(PoolConfig.newBuilder().build());
        ImagePipelineConfig.Builder builder =
                ImagePipelineConfig.newBuilder(getApplicationContext()).setPoolFactory(factory);
        Fresco.initialize(getApplicationContext(), builder.build());

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance());
        LynxServiceCenter.inst().registerService(LynxLogService.INSTANCE);
        LynxServiceCenter.inst().registerService(LynxHttpService.INSTANCE);
    }
}
```
</CodeFold>

  </Tab>
  <Tab label="Kotlin">

<CodeFold height={360} toggle>
```kotlin title=YourApplication.kt {15,18-27}
import android.app.Application
import com.facebook.drawee.backends.pipeline.Fresco
import com.facebook.imagepipeline.core.ImagePipelineConfig
import com.facebook.imagepipeline.memory.PoolConfig
import com.facebook.imagepipeline.memory.PoolFactory
import com.lynx.service.http.LynxHttpService
import com.lynx.service.image.LynxImageService
import com.lynx.service.log.LynxLogService
import com.lynx.tasm.service.LynxServiceCenter

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
    }

    private fun initLynxService() {
        // init Fresco which is needed by LynxImageService
        val factory = PoolFactory(PoolConfig.newBuilder().build())
        val builder = ImagePipelineConfig.newBuilder(applicationContext).setPoolFactory(factory)
        Fresco.initialize(applicationContext, builder.build())

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance())
        LynxServiceCenter.inst().registerService(LynxLogService)
        LynxServiceCenter.inst().registerService(LynxHttpService)
    }
}
```
</CodeFold>

  </Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### LynxEnv Initialization

LynxEnv provides the global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface calls to the Lynx Engine. It is recommended to complete the initialization of LynxEnv during the Application#onCreate lifecycle of the application.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
  <Tab label="Java">

<CodeFold height={360} toggle>
```java title=YourApplication.java {9,12-19}
import com.lynx.tasm.LynxEnv;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
        initLynxEnv();
    }

    private void initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        );
    }
}
```
</CodeFold>

</Tab>

  <Tab label="Kotlin">

<CodeFold height={360} toggle>
```kotlin title=YourApplication.kt {8,11-18}
import com.lynx.tasm.LynxEnv

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
        initLynxEnv()
    }

    private fun initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        )
    }
}
```
</CodeFold>

</Tab>
</Tabs>


:::tip

The parameters for the LynxEnv initialization method are described as follows:
- **appContext**: The context object for the application lifecycle, i.e., ApplicationContext.
- **libraryLoader**: The loader for native so files, the default value can be null, which will use the system default loader.
- **templateProvider**: The global AppBundle loader, the default value can be null;
- **behaviorBundle**: The list of custom components, the default value can be null. If there are customization requirements, please refer to [custom-native-component](/guide/custom-native-component)

:::

</Steps>

## 3. Render LynxView

<Steps>

### Create Bundle Loader
Lynx Engine itself does not have the ability to integrate downloading resources, so the existing app needs to provide the specific implementation of `AbsTemplateProvider`, and inject it when initializing LynxEnv or constructing [LynxView](/guide/spec.html#lynxview). Lynx will use the injected resource loader to obtain the Bundle content

You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.

1. First, please place the Bundle file generated in the [Quick Start](/guide/start/quick-start) stage in the src/main/assets directory, or you can download the file below to your local machine and place it in the same directory:

:::note
Bundle Example:
**https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle**
:::

```
app
└── src
    └── main
        ├── java
        ├── res
        └── assets
            └── main.lynx.bundle
```

2. Impl Bundle Loader

<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">

<CodeFold height={360} toggle>

```java title="DemoTemplateProvider.java" {}
import android.content.Context;
import com.lynx.tasm.provider.AbsTemplateProvider;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;

public class DemoTemplateProvider extends AbsTemplateProvider {
    private Context mContext;

    DemoTemplateProvider(Context context) {
        this.mContext = context.getApplicationContext();
    }

    @Override
    public void loadTemplate(String uri, Callback callback) {
        new Thread(new Runnable() {
            @Override
            public void run() {
                try (InputStream inputStream = mContext.getAssets().open(uri);
                     ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream()) {
                    byte[] buffer = new byte[1024];
                    int length;
                    while ((length = inputStream.read(buffer)) != -1) {
                        byteArrayOutputStream.write(buffer, 0, length);
                    }
                    callback.onSuccess(byteArrayOutputStream.toByteArray());
                } catch (IOException e) {
                    callback.onFailed(e.getMessage());
                }
            }
        }).start();
    }
}
```

</CodeFold>

</Tab>
<Tab label="Kotlin">

<CodeFold height={360} toggle>

```kotlin title="DemoTemplateProvider.kt" {}
import android.content.Context
import com.lynx.tasm.provider.AbsTemplateProvider
import java.io.ByteArrayOutputStream
import java.io.IOException

class DemoTemplateProvider(context: Context) : AbsTemplateProvider() {

    private var mContext: Context = context.applicationContext

    override fun loadTemplate(uri: String, callback: Callback) {
        Thread {
            try {
                mContext.assets.open(uri).use { inputStream ->
                    ByteArrayOutputStream().use { byteArrayOutputStream ->
                        val buffer = ByteArray(1024)
                        var length: Int
                        while ((inputStream.read(buffer).also { length = it }) != -1) {
                            byteArrayOutputStream.write(buffer, 0, length)
                        }
                        callback.onSuccess(byteArrayOutputStream.toByteArray())
                    }
                }
            } catch (e: IOException) {
                callback.onFailed(e.message)
            }
        }.start()
    }
}
```

</CodeFold>

</Tab>
</Tabs>

### Construct LynxView

`LynxView` is the basic rendering view provided by `Lynx Engine`. `LynxView` inherits from the native Android [View](https://developer.android.com/reference/android/view/View). You can quickly construct a LynxView and add it arbitrarily to the native Android view tree.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">
```java title=MainActivity.java {12-13,16-20}
import android.app.Activity;
import android.os.Bundle;

import com.lynx.tasm.LynxView;
import com.lynx.tasm.LynxViewBuilder;

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);
    }

    private LynxView buildLynxView() {
        LynxViewBuilder viewBuilder = new LynxViewBuilder();
        viewBuilder.setTemplateProvider(new DemoTemplateProvider(this));
        return viewBuilder.build(this);
    }
}
```
</Tab>

<Tab label="Kotlin">
```kotlin title=MainActivity.kt {11-12,15-19}
import android.app.Activity
import android.os.Bundle
import com.lynx.tasm.LynxView
import com.lynx.tasm.LynxViewBuilder


class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)
    }

    private fun buildLynxView(): LynxView {
        val viewBuilder = LynxViewBuilder()
        viewBuilder.setTemplateProvider(DemoTemplateProvider(this))
        return viewBuilder.build(this)
    }
}
```

</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### 3.1 Render view

After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.renderTemplateUrl` method to render the corresponding Bundle onto the LynxView view.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">

```java title=MainActivity.java {9-10}
public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);

        String url = "main.lynx.bundle";
        lynxView.renderTemplateUrl(url, "");
    }
}
```

</Tab>
<Tab label="Kotlin">

```kotlin title=MainActivity.kt {8-9}
class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)

        val uri = "main.lynx.bundle";
        lynxView.renderTemplateUrl(uri, "")
    }
}
```

</Tab>
</Tabs>

Then you will see the following interface on the screen:

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-android.png" width="200" />
</center>

</Steps>

Congratulations, you have now completed all the work of rendering the LynxView!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start) and [debugging](/guide/debugging/lynx-devtool) docs for in-depth insights on working with Lynx.

</PlatformTabs.Tab>

<PlatformTabs.Tab platform="web">
  ### Integrate Lynx with Existing Apps (Web)

import { PackageManagerTabs, Steps } from '@theme';
import { Info } from '@lynx';

<Info title="Lynx for Web">
  Lynx for Web implements the Lynx engine in web browsers. With Lynx for Web,
  you can easily integrate Lynx apps into any existing web project, regardless
  of whether the project uses React, Vue, Svelte, or plain HTML.
</Info>

## 1. Build web artifact

We need you to have read and created a Lynx project according to [Quick Start](/guide/start/quick-start).

<Steps>

### Add web configuration

1. Enter the previously created Lynx project:

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

2. Add web configuration (`environments.web`) to `lynx.config.ts`:

```ts
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [pluginReactLynx()],
  environments: {
    web: {
      output: {
        assetPrefix: '/',
      },
    },
    lynx: {},
  },
});
```

### Build

Run:

<PackageManagerTabs command="run build" />

You will see an additional `dist/main.web.bundle` file in this project, which is the final web build artifact.

</Steps>

## 2. Integrate with a new web project

Now that you have a Lynx for Web build artifact, we need to create a web project to use it. Here we use Rsbuild.

<Steps>

### Create a web project

Create a new project at the same level as the Lynx project above and run:

<PackageManagerTabs command="create rsbuild@latest" />

Follow the prompts to create a React project.

### Configure the project

1. Navigate to the created project:

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

2. Install dependencies

<PackageManagerTabs command="install @lynx-js/web-core @lynx-js/web-elements" />

3. Import these dependencies in `src/app.tsx`

```tsx
import './App.css';
import '@lynx-js/web-core/index.css';
import '@lynx-js/web-elements/index.css';
import '@lynx-js/web-core';
import '@lynx-js/web-elements/all';

const App = () => {
  return (
    <lynx-view
      style={{ height: '100vh', width: '100vw' }}
      url="/main.web.bundle"
    ></lynx-view>
  );
};

export default App;
```

4. Update `rsbuild.config.ts`

:::warning
`server.publicDir` needs to be replaced with your actual Lynx project path.
:::

```ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default defineConfig({
  plugins: [pluginReact()],
  server: {
    publicDir: [
      {
        name: path.join(
          __dirname,
          '../',
          // Please replace this with your actual Lynx project name
          'lynx-project',
          'dist',
        ),
      },
    ],
  },
});
```

### Start the project

Run:

<PackageManagerTabs command="run dev" />

Visit `http://localhost:3000` to see your Lynx application.

</Steps>

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

## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/Pictures.tar.gz) to use in your projects.

## Adding Styles

Since the focus of this tutorial is not on how to style your UI, you may just save some time and directly copy the below `index.css` file:

```css title="index.scss"
.gallery-wrapper {
  height: 100vh;
  background-color: black;
}

.single-card {
  display: flex;
  align-items: center;
  justify-content: center;
}

.scrollbar {
  position: absolute;
  right: 7px;
  z-index: 1000;
  width: 4px;
  background: linear-gradient(to bottom, #ff6448, #ccddff, #3deae7);
  border-radius: 5px;
  overflow: hidden;
  box-shadow:
    0px 0px 4px 1px rgba(12, 205, 223, 0.4),
    0px 0px 16px 5px rgba(12, 205, 223, 0.5);
}

.scrollbar-effect {
  width: 100%;
  height: 80%;
}

.glow {
  background-color: #333;
  border-radius: 4px;
  background: linear-gradient(
    45deg,
    rgba(255, 255, 255, 0) 20%,
    rgba(255, 255, 255, 0.8) 50%,
    rgba(255, 255, 255, 0) 80%
  );
  animation: flow 3s linear infinite;
}

@keyframes flow {
  0% {
    transform: translateY(-100%);
  }
  100% {
    transform: translateY(100%);
  }
}

.list {
  width: 100vw;
  padding-bottom: 20px;
  padding-left: 20px;
  padding-right: 20px;
  height: calc(100% - 48px);
  list-main-axis-gap: 10px;
  list-cross-axis-gap: 10px;
}

.picture-wrapper {
  border-radius: 10px;
  overflow: hidden;
  width: 100%;
}

.like-icon {
  position: absolute;
  display: grid;
  justify-items: center;
  align-items: center;
  top: 0px;
  right: 0px;
  width: 48px;
  height: 48px;
}

.heart-love {
  width: 16px;
  height: 16px;
}

.circle {
  position: absolute;
  top: calc(50% - 8px);
  left: calc(50% - 8px);
  height: 16px;
  width: 16px;
  border: 2px solid red;
  border-radius: 50%;
  transform: scale(0);
  opacity: 1;
  animation: ripple 1s 1 ease-out;
}

.circleAfter {
  animation-delay: 0.5s;
}

@keyframes ripple {
  0% {
    transform: scale(1);
    opacity: 1;
  }
  100% {
    transform: scale(2);
    opacity: 0;
  }
}
```

and import it as a global styles:

```js
import '../index.css';
```

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.

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

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

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

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:

Similar to the `bindtap` event used to add the like functionality, we add the bindscroll event to `<list>`, which will be triggered when the `<list>` element scrolls.

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

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:

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:

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.

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

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](/en/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/en/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>;
}
```

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](/en/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.

## 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](/en/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

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`](/en/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.

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

### 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`](/en/api/react/Function.runOnMainThread.md)
* From main thread to background: Use [`runOnBackground`](/en/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);
    }
  }
}
```

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:

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.

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.

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

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

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.

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

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.

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.

Scan the QR code to download the pre-built app from the [GitHub Release](https://github.com/lynx-family/lynx/releases/latest).

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

### Start developing

1. Navigate to the created project:

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

2. Install the NPM dependencies with package manager:

3) To start the development server, run:

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.

### 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/debugging/lynx-devtool.md), learn how to debug your Lynx app.

## Next steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

### Describing UI

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

### Integration

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



---
url: /rspeedy/start/integrate-with-existing-apps.md
---

import { PlatformTabs } from '@lynx';
import * as NextSteps from '@lynx/NextSteps';





# 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 hashKey="platform">
<PlatformTabs.Tab platform="ios">
### Integrate Lynx with Existing Apps (iOS)

import { Info, CodeFold } from '@lynx';
import { Steps } from '@theme';
import { Tab, Tabs } from 'rspress/theme';

<Info title="Lynx for iOS">
  - This article assumes that you are familiar with the basic concepts of native iOS application development.
  - You can refer to the project: [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/release/3.1) for all the code mentioned below.
</Info>

## 1. Dependency configuration

Using [Cocoapods](https://cocoapods.org/) can easily integrate Lynx into your application

<Info title="Recommended Versions">

- Cocoapods: >= 1.11.3
- Ruby: >= 2.6.10

</Info>

<Steps>

### Configuring Deps

1. **Lynx**

The core capabilities of [Lynx Engine](/guide/spec.html#engine) include basic capabilities such as parsing [Bundle](/guide/spec.html#lynx-bundle-or-bundle), style parsing, layout, and rendering views

Get the latest version of Lynx from Cocoapods. Then add Lynx to your Podfile:

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

2. **Lynx Service**

Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official. For example, `LynxImageService` is implemented using the [SDWebImage](https://github.com/SDWebImage/SDWebImage) image library by default. Apps that do not integrate SDWebImage components can rely on other image libraries to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;

Get the latest version of Lynx Service from Cocoapods. Then add Lynx Service to your Podfile:

<CodeFold height={360} toggle>

```ruby title="Podfile" {13-17,20-21}
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 dependencies:
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'
end
```

</CodeFold>

### Install Dependencies

Run `pod install` to install dependencies, then open your Xcode project. Additionally, make sure to disable the Sandbox Scripting capability.

:::note

In order to disable the **Sandbox scripting**, in Xcode click on your app, then on **build settings**. Filter for **script** and set the **User Script Sandboxing** to **NO**.

<img
  height="180px"
  width="640px"
  src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/integration_ios_warning.png"
/>
:::

</Steps>

## 2. Lynx Environment Initialization

<Steps>

### LynxEnv Initialization

LynxEnv provides a global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface call of the Lynx Engine.
For example, it can be initialized in `AppDelegate`

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">

```objective-c title=AppDelegate.m {6}
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxView.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [LynxEnv sharedInstance];
  return YES;
}
```

</Tab>
<Tab label="Swift">

```swift title=AppDelegate.swift {8}
import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    LynxEnv.sharedInstance()
    return true
  }
}

```
</Tab>
</Tabs>

</Steps>

## 3. Render LynxView

LynxView is the basic rendering unit provided by Lynx Engine. LynxView is an implementation inherited from iOS native [UIView](https://developer.apple.com/documentation/uikit/uiview). You can quickly construct a LynxView and add it to the [ViewController](https://developer.apple.com/documentation/uikit/uitab/viewcontroller/).

<Steps>


### Create Bundle Loader

Lynx Engine itself does not have the ability to load resources, so it is necessary to initialize LynxEnv, or when constructing [LynxView](/guide/spec.html#lynxview) to pass in the specific implementation of the `LynxTemplateProvider` protocol. Lynx will use the injected resource loader to obtain the Bundle content

You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.

1. First, please either generate the Bundle file from the [Quick Start](/guide/start/quick-start) phase or download the file below to your local machine, and then follow these steps to embed the file:

:::note
Bundle Example:
**https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle**
:::


:::note

Steps to embed files:
- In the target settings of the project, select the target;
- Select the **Build Phases** tab;
- In the **Copy Bundle Resources** section, click the add button (+) to add the file;

:::


2. Impl Bundle Loader

<Tabs groupId='integrating-lynx-with-existing-app-ios'>
<Tab label="Objective-C">

```objective-c title="DemoLynxProvider.h"
#import <Foundation/Foundation.h>
#import <Lynx/LynxTemplateProvider.h>

NS_ASSUME_NONNULL_BEGIN

@interface DemoLynxProvider : NSObject <LynxTemplateProvider>

@end

NS_ASSUME_NONNULL_END
```

</Tab>
<Tab label="Swift">

:::tip

Use [Bridging Header](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift) to import the required Lynx header files if you are using a Swift project, since Lynx is a project built with Objective-C.

:::

``` objective-c title="YourTarget-Bridging-Header.h"
#import <Lynx/LynxConfig.h>
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxTemplateProvider.h>
#import <Lynx/LynxView.h>
```

</Tab>
</Tabs>

<div style={{ marginBottom: 20 }} />

<Tabs groupId='integrating-lynx-with-existing-app-ios'>
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="DemoLynxProvider.m"
#import <Foundation/Foundation.h>

#import "DemoLynxProvider.h"

@implementation DemoLynxProvider

- (void)loadTemplateWithUrl:(NSString*)url onComplete:(LynxTemplateLoadBlock)callback {
    NSString *filePath = [[NSBundle mainBundle] pathForResource:url ofType:@"bundle"];
    if (filePath) {
      NSError *error;
      NSData *data = [NSData dataWithContentsOfFile:filePath options:0 error:&error];
      if (error) {
        NSLog(@"Error reading file: %@", error.localizedDescription);
        callback(nil, error);
      } else {
        callback(data, nil);
      }
    } else {
      NSError *urlError = [NSError errorWithDomain:@"com.lynx"
                                                  code:400
                                                userInfo:@{NSLocalizedDescriptionKey : @"Invalid URL."}];
      callback(nil, urlError);
    }
}

@end
```

</CodeFold>
</Tab>

<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="DemoLynxProvider.swift"
import Foundation

class DemoLynxProvider: NSObject, LynxTemplateProvider {
  func loadTemplate(withUrl url: String!, onComplete callback: LynxTemplateLoadBlock!) {
    if let filePath = Bundle.main.path(forResource: url, ofType: "bundle") {
      do {
        let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
        callback(data, nil)
      } catch {
        print("Error reading file: \(error.localizedDescription)")
        callback(nil, error)
      }
    } else {
      let urlError = NSError(domain: "com.lynx", code: 400, userInfo: [NSLocalizedDescriptionKey: "Invalid URL."])
      callback(nil, urlError)
    }
  }
}
```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Construct Basic LynxView

you may construct a basic LynxView as follows:

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {10-18}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
      builder.config = [[LynxConfig alloc] initWithProvider:[[DemoLynxProvider alloc] init]];
      builder.screenSize = self.view.frame.size;
      builder.fontScale = 1.0;
    }];
    lynxView.preferredLayoutWidth = self.view.frame.size.width;
    lynxView.preferredLayoutHeight = self.view.frame.size.height;
    lynxView.layoutWidthMode = LynxViewSizeModeExact;
    lynxView.layoutHeightMode = LynxViewSizeModeExact;
}
@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title=ViewController.swift {8-17}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    let lynxView = LynxView { builder in
      builder.config = LynxConfig(provider: DemoLynxProvider())
      builder.screenSize = self.view.frame.size
      builder.fontScale = 1.0
    }

    lynxView.preferredLayoutWidth = self.view.frame.size.width
    lynxView.preferredLayoutHeight = self.view.frame.size.height
    lynxView.layoutWidthMode = .exact
    lynxView.layoutHeightMode = .exact
  }
}
```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Add LynxView To The Window:

and then, adding the LynxView to the window.

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [self.view addSubview:lynxView];
}

@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    self.view.addSubview(lynxView)
  }
}

```

</CodeFold>
</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### Render View

After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.loadTemplateFromURL` method to render the corresponding Bundle onto the LynxView.

<Tabs groupId="integrating-lynx-with-existing-app-ios">
<Tab label="Objective-C">
<CodeFold height={360} toggle>

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [lynxView loadTemplateFromURL:@"main.lynx" initData:nil];
}

@end
```

</CodeFold>
</Tab>
<Tab label="Swift">
<CodeFold height={360} toggle>

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    lynxView.loadTemplate(fromURL: "main.lynx", initData: nil)
  }
}

```

</CodeFold>
</Tab>
</Tabs>

Then you will see the following interface on the screen:

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-ios.png" width="200" />
</center>

</Steps>

Congratulations, you have now completed all the work of integrating Lynx Engine!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start) and [debugging](/guide/debugging/lynx-devtool) docs for in-depth insights on working with Lynx.

</PlatformTabs.Tab>

<PlatformTabs.Tab platform="android">
  ### Integrate Lynx with Existing Apps (Android)

import { Info, CodeFold } from '@lynx';
import { Steps } from '@theme';
import { Tab, Tabs } from 'rspress/theme';

<Info title="Lynx for Android">
  - This article assumes that you are familiar with the basic concepts of native Android application development.
  - You can refer to the project: [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/release/3.1) for all the code mentioned below.
</Info>

## 1. Dependency configuration

<Steps>

### Configuring Gradle

1. **Lynx**

The core capabilities of [Lynx Engine](/guide/spec.html#engine) include basic capabilities such as parsing [Bundle](/guide/spec.html#lynx-bundle-or-bundle), style parsing, layout, rendering views and the basic code of the javascript runtime that Lynx pages rely on

<Tabs groupId='integrating-lynx-with-existing-app-android-build'>
<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>

2. **Lynx Service**

Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official.For example, `LynxImageService` is implemented using the [Fresco](https://github.com/facebook/fresco) image library by default. Apps that do not integrate Fresco components can rely on other image libraries, such as [Glide](https://github.com/bumptech/glide) to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;

:::note
Since [Fresco](https://github.com/facebook/fresco) depends on [AndroidX](https://developer.android.com/jetpack/androidx), you also need to configure the following in gradle.properties:

```groovy
android.useAndroidX=true
```

:::

<Tabs groupId='integrating-lynx-with-existing-app-android-build'>
<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"

    implementation "com.squareup.okhttp3:okhttp:4.9.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"
}
```
</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>

<div style={{ marginBottom: 30 }} />

### Configure obfuscation rules ([Proguard](https://developer.android.com/build/shrink-code))

The obfuscation rules for` Lynx Engine` are as follows. It is recommended to refer to the latest source code configuration.

<CodeFold height={360} toggle>

```groovy title=proguard-rules.pro
# LYNX START
# use @Keep to annotate retained classes.
-dontwarn android.support.annotation.Keep
-keep @android.support.annotation.Keep class **
-keep @android.support.annotation.Keep class ** {
    @android.support.annotation.Keep <fields>;
    @android.support.annotation.Keep <methods>;
}
-dontwarn androidx.annotation.Keep
-keep @androidx.annotation.Keep class **
-keep @androidx.annotation.Keep class ** {
    @androidx.annotation.Keep <fields>;
    @androidx.annotation.Keep <methods>;
}

# native method call
-keepclasseswithmembers,includedescriptorclasses class * {
    native <methods>;
}
-keepclasseswithmembers class * {
    @com.lynx.tasm.base.CalledByNative <methods>;
}

# to customize a module, you need to keep the class name and the method annotated as LynxMethod.
-keepclasseswithmembers class * {
    @com.lynx.jsbridge.LynxMethod <methods>;
}

-keepclassmembers class *  {
    @com.lynx.tasm.behavior.LynxProp <methods>;
    @com.lynx.tasm.behavior.LynxPropGroup <methods>;
    @com.lynx.tasm.behavior.LynxUIMethod <methods>;
}

-keepclassmembers class com.lynx.tasm.behavior.ui.UIGroup {
    public boolean needCustomLayout();
}

# in case R8 compiler may remove mLoader in bytecode.
# as mLoader is not used in java and passed as a WeakRef in JNI.
-keepclassmembers class com.lynx.tasm.LynxTemplateRender {
    private com.lynx.tasm.core.LynxResourceLoader mLoader;
}

# the automatically generated setter classes use the class names of LynxBaseUI and ShadowNode and their subclasses.
-keep class com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class com.lynx.tasm.behavior.shadow.ShadowNode
-keep class com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class * extends com.lynx.tasm.behavior.shadow.ShadowNode
-keep class * extends com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.jsbridge.LynxContextModule
-keep class * implements com.lynx.tasm.behavior.utils.Settable
-keep class * implements com.lynx.tasm.behavior.utils.LynxUISetter
-keep class * implements com.lynx.tasm.behavior.utils.LynxUIMethodInvoker
-keep class com.lynx.tasm.rendernode.compat.**{
    *;
}
-keep class com.lynx.tasm.rendernode.compat.RenderNodeFactory{
    *;
}
# LYNX END
```

</CodeFold>

</Steps>

## 2. Environment Initialization

<Steps>

### Lynx Service Initialization

- Lynx Service provides host feature-related capabilities and it is recommended to complete the initialization of Lynx Service during the `Application#onCreate` lifecycle of the application.
- Lynx Service needs to be actively injected

:::tip

Please specify your custom Application class in the AndroidManifest.xml file, since Lynx needs to perform some global initialization operations when the application starts.

```xml title="/app/src/main/AndroidManifest.xml" {2}
<application
  android:name=".YourApplication">
</application>
```

:::

<Tabs groupId='integrating-lynx-with-existing-app-android'>
  <Tab label="Java">

<CodeFold height={360} toggle>
```java title=YourApplication.java {17,20-30}
import android.app.Application;

import com.facebook.drawee.backends.pipeline.Fresco;
import com.facebook.imagepipeline.core.ImagePipelineConfig;
import com.facebook.imagepipeline.memory.PoolConfig;
import com.facebook.imagepipeline.memory.PoolFactory;
import com.lynx.service.http.LynxHttpService;
import com.lynx.service.image.LynxImageService;
import com.lynx.service.log.LynxLogService;
import com.lynx.tasm.service.LynxServiceCenter;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
    }

    private void initLynxService() {
        // init Fresco which is needed by LynxImageService
        final PoolFactory factory = new PoolFactory(PoolConfig.newBuilder().build());
        ImagePipelineConfig.Builder builder =
                ImagePipelineConfig.newBuilder(getApplicationContext()).setPoolFactory(factory);
        Fresco.initialize(getApplicationContext(), builder.build());

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance());
        LynxServiceCenter.inst().registerService(LynxLogService.INSTANCE);
        LynxServiceCenter.inst().registerService(LynxHttpService.INSTANCE);
    }
}
```
</CodeFold>

  </Tab>
  <Tab label="Kotlin">

<CodeFold height={360} toggle>
```kotlin title=YourApplication.kt {15,18-27}
import android.app.Application
import com.facebook.drawee.backends.pipeline.Fresco
import com.facebook.imagepipeline.core.ImagePipelineConfig
import com.facebook.imagepipeline.memory.PoolConfig
import com.facebook.imagepipeline.memory.PoolFactory
import com.lynx.service.http.LynxHttpService
import com.lynx.service.image.LynxImageService
import com.lynx.service.log.LynxLogService
import com.lynx.tasm.service.LynxServiceCenter

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
    }

    private fun initLynxService() {
        // init Fresco which is needed by LynxImageService
        val factory = PoolFactory(PoolConfig.newBuilder().build())
        val builder = ImagePipelineConfig.newBuilder(applicationContext).setPoolFactory(factory)
        Fresco.initialize(applicationContext, builder.build())

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance())
        LynxServiceCenter.inst().registerService(LynxLogService)
        LynxServiceCenter.inst().registerService(LynxHttpService)
    }
}
```
</CodeFold>

  </Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### LynxEnv Initialization

LynxEnv provides the global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface calls to the Lynx Engine. It is recommended to complete the initialization of LynxEnv during the Application#onCreate lifecycle of the application.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
  <Tab label="Java">

<CodeFold height={360} toggle>
```java title=YourApplication.java {9,12-19}
import com.lynx.tasm.LynxEnv;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
        initLynxEnv();
    }

    private void initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        );
    }
}
```
</CodeFold>

</Tab>

  <Tab label="Kotlin">

<CodeFold height={360} toggle>
```kotlin title=YourApplication.kt {8,11-18}
import com.lynx.tasm.LynxEnv

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
        initLynxEnv()
    }

    private fun initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        )
    }
}
```
</CodeFold>

</Tab>
</Tabs>


:::tip

The parameters for the LynxEnv initialization method are described as follows:
- **appContext**: The context object for the application lifecycle, i.e., ApplicationContext.
- **libraryLoader**: The loader for native so files, the default value can be null, which will use the system default loader.
- **templateProvider**: The global AppBundle loader, the default value can be null;
- **behaviorBundle**: The list of custom components, the default value can be null. If there are customization requirements, please refer to [custom-native-component](/guide/custom-native-component)

:::

</Steps>

## 3. Render LynxView

<Steps>

### Create Bundle Loader
Lynx Engine itself does not have the ability to integrate downloading resources, so the existing app needs to provide the specific implementation of `AbsTemplateProvider`, and inject it when initializing LynxEnv or constructing [LynxView](/guide/spec.html#lynxview). Lynx will use the injected resource loader to obtain the Bundle content

You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.

1. First, please place the Bundle file generated in the [Quick Start](/guide/start/quick-start) stage in the src/main/assets directory, or you can download the file below to your local machine and place it in the same directory:

:::note
Bundle Example:
**https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle**
:::

```
app
└── src
    └── main
        ├── java
        ├── res
        └── assets
            └── main.lynx.bundle
```

2. Impl Bundle Loader

<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">

<CodeFold height={360} toggle>

```java title="DemoTemplateProvider.java" {}
import android.content.Context;
import com.lynx.tasm.provider.AbsTemplateProvider;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;

public class DemoTemplateProvider extends AbsTemplateProvider {
    private Context mContext;

    DemoTemplateProvider(Context context) {
        this.mContext = context.getApplicationContext();
    }

    @Override
    public void loadTemplate(String uri, Callback callback) {
        new Thread(new Runnable() {
            @Override
            public void run() {
                try (InputStream inputStream = mContext.getAssets().open(uri);
                     ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream()) {
                    byte[] buffer = new byte[1024];
                    int length;
                    while ((length = inputStream.read(buffer)) != -1) {
                        byteArrayOutputStream.write(buffer, 0, length);
                    }
                    callback.onSuccess(byteArrayOutputStream.toByteArray());
                } catch (IOException e) {
                    callback.onFailed(e.getMessage());
                }
            }
        }).start();
    }
}
```

</CodeFold>

</Tab>
<Tab label="Kotlin">

<CodeFold height={360} toggle>

```kotlin title="DemoTemplateProvider.kt" {}
import android.content.Context
import com.lynx.tasm.provider.AbsTemplateProvider
import java.io.ByteArrayOutputStream
import java.io.IOException

class DemoTemplateProvider(context: Context) : AbsTemplateProvider() {

    private var mContext: Context = context.applicationContext

    override fun loadTemplate(uri: String, callback: Callback) {
        Thread {
            try {
                mContext.assets.open(uri).use { inputStream ->
                    ByteArrayOutputStream().use { byteArrayOutputStream ->
                        val buffer = ByteArray(1024)
                        var length: Int
                        while ((inputStream.read(buffer).also { length = it }) != -1) {
                            byteArrayOutputStream.write(buffer, 0, length)
                        }
                        callback.onSuccess(byteArrayOutputStream.toByteArray())
                    }
                }
            } catch (e: IOException) {
                callback.onFailed(e.message)
            }
        }.start()
    }
}
```

</CodeFold>

</Tab>
</Tabs>

### Construct LynxView

`LynxView` is the basic rendering view provided by `Lynx Engine`. `LynxView` inherits from the native Android [View](https://developer.android.com/reference/android/view/View). You can quickly construct a LynxView and add it arbitrarily to the native Android view tree.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">
```java title=MainActivity.java {12-13,16-20}
import android.app.Activity;
import android.os.Bundle;

import com.lynx.tasm.LynxView;
import com.lynx.tasm.LynxViewBuilder;

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);
    }

    private LynxView buildLynxView() {
        LynxViewBuilder viewBuilder = new LynxViewBuilder();
        viewBuilder.setTemplateProvider(new DemoTemplateProvider(this));
        return viewBuilder.build(this);
    }
}
```
</Tab>

<Tab label="Kotlin">
```kotlin title=MainActivity.kt {11-12,15-19}
import android.app.Activity
import android.os.Bundle
import com.lynx.tasm.LynxView
import com.lynx.tasm.LynxViewBuilder


class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)
    }

    private fun buildLynxView(): LynxView {
        val viewBuilder = LynxViewBuilder()
        viewBuilder.setTemplateProvider(DemoTemplateProvider(this))
        return viewBuilder.build(this)
    }
}
```

</Tab>
</Tabs>

<div style={{ marginBottom: 30 }} />

### 3.1 Render view

After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.renderTemplateUrl` method to render the corresponding Bundle onto the LynxView view.


<Tabs groupId='integrating-lynx-with-existing-app-android'>
<Tab label="Java">

```java title=MainActivity.java {9-10}
public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);

        String url = "main.lynx.bundle";
        lynxView.renderTemplateUrl(url, "");
    }
}
```

</Tab>
<Tab label="Kotlin">

```kotlin title=MainActivity.kt {8-9}
class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)

        val uri = "main.lynx.bundle";
        lynxView.renderTemplateUrl(uri, "")
    }
}
```

</Tab>
</Tabs>

Then you will see the following interface on the screen:

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-android.png" width="200" />
</center>

</Steps>

Congratulations, you have now completed all the work of rendering the LynxView!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start) and [debugging](/guide/debugging/lynx-devtool) docs for in-depth insights on working with Lynx.

</PlatformTabs.Tab>

<PlatformTabs.Tab platform="web">
  ### Integrate Lynx with Existing Apps (Web)

import { PackageManagerTabs, Steps } from '@theme';
import { Info } from '@lynx';

<Info title="Lynx for Web">
  Lynx for Web implements the Lynx engine in web browsers. With Lynx for Web,
  you can easily integrate Lynx apps into any existing web project, regardless
  of whether the project uses React, Vue, Svelte, or plain HTML.
</Info>

## 1. Build web artifact

We need you to have read and created a Lynx project according to [Quick Start](/guide/start/quick-start).

<Steps>

### Add web configuration

1. Enter the previously created Lynx project:

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

2. Add web configuration (`environments.web`) to `lynx.config.ts`:

```ts
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [pluginReactLynx()],
  environments: {
    web: {
      output: {
        assetPrefix: '/',
      },
    },
    lynx: {},
  },
});
```

### Build

Run:

<PackageManagerTabs command="run build" />

You will see an additional `dist/main.web.bundle` file in this project, which is the final web build artifact.

</Steps>

## 2. Integrate with a new web project

Now that you have a Lynx for Web build artifact, we need to create a web project to use it. Here we use Rsbuild.

<Steps>

### Create a web project

Create a new project at the same level as the Lynx project above and run:

<PackageManagerTabs command="create rsbuild@latest" />

Follow the prompts to create a React project.

### Configure the project

1. Navigate to the created project:

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

2. Install dependencies

<PackageManagerTabs command="install @lynx-js/web-core @lynx-js/web-elements" />

3. Import these dependencies in `src/app.tsx`

```tsx
import './App.css';
import '@lynx-js/web-core/index.css';
import '@lynx-js/web-elements/index.css';
import '@lynx-js/web-core';
import '@lynx-js/web-elements/all';

const App = () => {
  return (
    <lynx-view
      style={{ height: '100vh', width: '100vw' }}
      url="/main.web.bundle"
    ></lynx-view>
  );
};

export default App;
```

4. Update `rsbuild.config.ts`

:::warning
`server.publicDir` needs to be replaced with your actual Lynx project path.
:::

```ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default defineConfig({
  plugins: [pluginReact()],
  server: {
    publicDir: [
      {
        name: path.join(
          __dirname,
          '../',
          // Please replace this with your actual Lynx project name
          'lynx-project',
          'dist',
        ),
      },
    ],
  },
});
```

### Start the project

Run:

<PackageManagerTabs command="run dev" />

Visit `http://localhost:3000` to see your Lynx application.

</Steps>

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

## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/Pictures.tar.gz) to use in your projects.

## Adding Styles

Since the focus of this tutorial is not on how to style your UI, you may just save some time and directly copy the below `index.css` file:

```css title="index.scss"
.gallery-wrapper {
  height: 100vh;
  background-color: black;
}

.single-card {
  display: flex;
  align-items: center;
  justify-content: center;
}

.scrollbar {
  position: absolute;
  right: 7px;
  z-index: 1000;
  width: 4px;
  background: linear-gradient(to bottom, #ff6448, #ccddff, #3deae7);
  border-radius: 5px;
  overflow: hidden;
  box-shadow:
    0px 0px 4px 1px rgba(12, 205, 223, 0.4),
    0px 0px 16px 5px rgba(12, 205, 223, 0.5);
}

.scrollbar-effect {
  width: 100%;
  height: 80%;
}

.glow {
  background-color: #333;
  border-radius: 4px;
  background: linear-gradient(
    45deg,
    rgba(255, 255, 255, 0) 20%,
    rgba(255, 255, 255, 0.8) 50%,
    rgba(255, 255, 255, 0) 80%
  );
  animation: flow 3s linear infinite;
}

@keyframes flow {
  0% {
    transform: translateY(-100%);
  }
  100% {
    transform: translateY(100%);
  }
}

.list {
  width: 100vw;
  padding-bottom: 20px;
  padding-left: 20px;
  padding-right: 20px;
  height: calc(100% - 48px);
  list-main-axis-gap: 10px;
  list-cross-axis-gap: 10px;
}

.picture-wrapper {
  border-radius: 10px;
  overflow: hidden;
  width: 100%;
}

.like-icon {
  position: absolute;
  display: grid;
  justify-items: center;
  align-items: center;
  top: 0px;
  right: 0px;
  width: 48px;
  height: 48px;
}

.heart-love {
  width: 16px;
  height: 16px;
}

.circle {
  position: absolute;
  top: calc(50% - 8px);
  left: calc(50% - 8px);
  height: 16px;
  width: 16px;
  border: 2px solid red;
  border-radius: 50%;
  transform: scale(0);
  opacity: 1;
  animation: ripple 1s 1 ease-out;
}

.circleAfter {
  animation-delay: 0.5s;
}

@keyframes ripple {
  0% {
    transform: scale(1);
    opacity: 1;
  }
  100% {
    transform: scale(2);
    opacity: 0;
  }
}
```

and import it as a global styles:

```js
import '../index.css';
```

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.

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

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

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

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:

Similar to the `bindtap` event used to add the like functionality, we add the bindscroll event to `<list>`, which will be triggered when the `<list>` element scrolls.

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

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:

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:

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.

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

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](/en/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/en/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>;
}
```

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](/en/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.

## 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](/en/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

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`](/en/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.

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

### 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`](/en/api/react/Function.runOnMainThread.md)
* From main thread to background: Use [`runOnBackground`](/en/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);
    }
  }
}
```

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:

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.

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.

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