> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# What is lynx-ui?

`@lynx-js/lynx-ui` is the official **headless UI library** built for **ReactLynx**, the most popular framework for building Lynx apps. It reconciles **cross-platform differences** in UI behavior and APIs, providing **consistent**, **high-performance** frontend components on top of Lynx's low-level primitives.

## Quick Start

`lynx-ui` supports both full-library imports and individual component imports.

### Full-Library Import (Recommended)

Install and import the main `lynx-ui` package. Tree-shaking is supported, so unused components will not increase your final bundle size.


```sh [npm]
npm install @lynx-js/lynx-ui
```

```sh [yarn]
yarn add @lynx-js/lynx-ui
```

```sh [pnpm]
pnpm add @lynx-js/lynx-ui
```

```sh [bun]
bun add @lynx-js/lynx-ui
```

```sh [deno]
deno add npm:@lynx-js/lynx-ui
```

Use it in your project:

```jsx {1}
import { Button } from '@lynx-js/lynx-ui';

export default function App() {
  return (
    <view>
      <Button />
    </view>
  );
}
```

### Importing Individual Components

Each `lynx-ui` component is also published as a separate package. Use this approach when you have compatibility constraints or need to depend on a specific component package.

For example, to use `<Button>`:


```sh [npm]
npm install @lynx-js/lynx-ui-button
```

```sh [yarn]
yarn add @lynx-js/lynx-ui-button
```

```sh [pnpm]
pnpm add @lynx-js/lynx-ui-button
```

```sh [bun]
bun add @lynx-js/lynx-ui-button
```

```sh [deno]
deno add npm:@lynx-js/lynx-ui-button
```

Use it in your project:

```jsx {1}
import { Button } from '@lynx-js/lynx-ui-button';

export default function App() {
  return (
    <view>
      <Button />
    </view>
  );
}
```

:::details Which way should I choose
We recommend full-library imports by default:

1. Installation and usage are simpler

2. Tree-shaking keeps the final bundle size small

:::

## Configuration

```typescript
export default defineConfig({
  ...
  plugins: [
    pluginReactLynx({
      ...
      enableNewGesture: true,
    }),
  ],
})
```

:::details Concerned about configuration changes affecting other pages?
This page lists the requirements for the full library. If you need looser constraints, check the configuration requirements of the specific components you use.
:::

## Compatibility

- [Lynx Engine](/next/guide/build/index.md#compatibility): >= 3.2
- Platforms: full support for **iOS** and **Android**, with ongoing improvements for **Harmony**, **Web**, and **Desktop**

:::details Version not supported?
These are the requirements for the full library. Individual components may support lower versions.
:::

## Further Resources

lynx-ui components make heavy use of [**Main Thread Script**](/next/react/main-thread-script.md), which runs interaction logic directly on the main thread for smoother, more responsive experiences. To understand how it works, see the [Main Thread Script guide](/next/react/main-thread-script.md) in the ReactLynx docs.

If you use AI-assisted development, [lynx-ui Skills](/next/ai/skills/lynx-ui.md) provides pre-configured component references that help coding agents generate more accurate lynx-ui code.

## Building with the Community

lynx-ui is a place to explore and validate new ideas for Lynx components. We welcome contributions from the community and hope to make every improvement visible and reusable.

### Share Real-World Use Cases

Whether you are building e-commerce, social, live-streaming, or other types of apps, we welcome real-world cases from your development practice. If you discover meaningful interactions, stability improvements, or performance optimizations, lynx-ui can help refine them into reusable components with appropriate compatibility and performance considerations.

### Explore New Interaction Patterns

lynx-ui is committed to advancing interaction design in Lynx. We look forward to working with the community to discuss, iterate on, and implement practical solutions for more expressive user experiences.

### Grow the Lynx Ecosystem

Your experience with Lynx development is essential to the growth of the ecosystem. We sincerely welcome your feedback, participation, and contributions.

Visit the [GitHub repository](https://github.com/lynx-family/lynx-ui) to get started, or read the [Contribution Guide](https://github.com/lynx-family/lynx-ui/blob/main/CONTRIBUTING.md) for details.
