#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: You'll learn how to listen to events and update node styles
• Use Main Thread Script to Reduce Latency: You'll learn how to optimize interaction performance with main thread script
• 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: 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, then scan the QR code below.

The swiper responds to touch, so the web preview below demonstrates it for you: the swipes are simulated, and the circle marks where a finger would be. Touch or click the preview at any time and it hands control straight back to you.

swipersrc/Swiper/App.tsx

Code

Preview

#Setup for the tutorial

Check out our detailed quick start 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 to use in your projects.

#Direct Node Manipulation

Here's a product detail page example that includes a swiper and some product details. The <Swiper> accepts images and displays them in a row. Currently, it can't scroll - let's make it interactive.

The demonstration swipes this one too, and nothing moves — that is the point. Nothing here listens for the gesture yet.

swipersrc/SwiperEmpty/App.tsx

Code

Preview

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.

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.

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.

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 to get the swiper-container node and use setNativeProps to update the transform property, thereby updating the scroll position.

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

swipersrc/UpdateOffset/Swiper.tsx

Code

Preview

Now the <Swiper> component can scroll with finger movements!

function Swiper() {
  const [offset, setOffset] = useState(0);

  return (
    <view style={{ transform: `translateX(${offset}px)` }}>{/* ... */}</view>
  );
}

#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 code into useOffset, centralizing all scroll-related logic in this hook
2. Encapsulate the scroll position update code into useUpdateSwiperStyle, centralizing all <Swiper> component style update logic in this hook

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.

swipersrc/SwiperHooks/Swiper.tsx

Code

Preview

#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 to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

swipersrc/SwiperMTS/Swiper.tsx

Code

Preview

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.

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.

<view
  main-thread:bindtouchstart={handleTouchStart}
  main-thread:bindtouchmove={handleTouchMove}
>
  {/* ... */}
</view>

#useUpdateSwiperStyle

Convert useRef to useMainThreadRef.

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.

<view main-thread:ref={swiperContainerRef}>{/* ... */}</view>

The main thread node provides many capabilities, as shown in MainThread.Element. Here we call the setStyleProperties method to modify the transform property, updating the <Swiper> component's position.

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.

swipersrc/SwiperMTS/Swiper.tsx

Code

Preview

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

swipersrc/MTSIndicatorEmpty/Swiper.tsx

Code

Preview

#Main Thread Calling Background Thread

The core of the progress indicator is the <Indicator> component, which accepts a current prop indicating the current page.

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.

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.

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

onIndexUpdate is a background thread function. When called in a main thread function, we need to use runOnBackground

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

swipersrc/MTSIndicatorCurrent/Swiper.tsx

Code

Preview

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.

function useOffset({ itemWidth, onIndexUpdate }) {
  function updateIndex(index: number) {
    const offset = index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  return {
    updateIndex,
  };
}

Here's the complete code:

swipersrc/MTSIndicator/useOffset.ts

Code

Preview

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.

swipersrc/EasingDefault/useOffset.ts

Code

Preview

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.

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

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.

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

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

function Swiper({
  'main-thread:easing': MTEasing,
}) {
  ...
  const { handleTouchStart, ... } = useOffset({
    MTEasing,
  });
}

And in useOffset, it's passed to the main thread function animate.

function useOffset({
  duration,
  MTEasing,
}) {
  ...
  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    // ...
    animate({
      duration,
      easing: MTEasing,
    });
  }
}

function Swiper({ 'main-thread:easing': MTEasing }) {}

Finally, we have a swiper with customizable animation curves.

swipersrc/Swiper/App.tsx

Code

Preview

#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