Level Up Your Compose Modifiers: Mastering the Node API

In my previous article, we explored the basics of creating custom modifiers in Jetpack Compose. We learned how to extend the `Modifier` interface to add custom behaviour to our composable. Today, we’re taking a step further by diving into the Node API, a more powerful approach to creating complex custom modifiers.

Why Use the Node API?

The Node API provides several advantages over the traditional approach:

1. Better Performance: The Node API is designed to be more efficient, especially for complex modifiers that need to interact with the layout system.

2. More Control: It gives you direct access to layout coordinates and positioning information, allowing for more sophisticated behaviours.

3. Lifecycle Management: The Node API provides better lifecycle management for modifiers, ensuring that resources are properly cleaned up.

4. Improved Testability: Modifiers built with the Node API are easier to test in isolation.

5. Enhanced Debugging: The API includes built-in inspector support, making it easier to debug issues with your custom modifiers.

According to the Compose documentation, the Node API is the recommended approach for creating custom modifiers that need to interact with the layout system or track position information.

Our Example: A trackVisibility Modifier

Let’s build a custom modifier that tracks how visible a composable is on the screen and informs us of its state. We want to know:

• Is the composable visible at all?
• What percentage of the composable is visible?
• What are the screen bounds of the visible area?
• Is the composable visible above a threshold?

Visibility Tracking is an important aspect for media apps

- Reduced Resource Consumption: Only videos that are significantly visible are actively playing. This saves bandwidth, CPU, and battery.

- Improved User Experience: Videos automatically play and pause as the user scrolls, creating a smooth, intuitive experience.

- Optimised Performance: By pausing off-screen videos, we reduce the number of active media players, which prevents potential performance issues.

This is more advanced than the examples in the previous blog post, but it’s a great way to demonstrate the power of the Node API.

Step 1: Define the VisibilityInfo Data Class

We start by creating a data class to hold the information our modifier will provide:

This class provides a clear and concise way to encapsulate all the visibility details we care about.

Step 2: Create the VisibilityTrackerNode

Next, we define VisibilityTrackerNode, which will implement the core logic of our modifier:

Let’s examine the code in detail:

• Modifier.Node(), GlobalPositionAwareModifierNode: This indicates that our class is a modifier node that’s also aware of its global position.
• thresholdPercentage: This variable indicates the threshold at which the element is considered “visible enough”.
• onVisibilityChanged: It’s a callback that receives VisibilityInfo to let you know about visibility changes.
• previousVisibilityPercentage: This variable keeps track of the last percentage reported to avoid excessive updates.
• minimumVisibilityDelta: Is the minimal difference to update the visibility info.
• onGloballyPositioned: This is where the magic happens. It’s called when the composable’s layout is determined.

Step 3: Create VisibilityTrackerElement

Now, we need to create a ModifierNodeElement that will act as the factory for our VisibilityTrackerNode:

• ModifierNodeElement<VisibilityTrackerNode>: This is the base class for our element.
• create(): This method is called to instantiate a new VisibilityTrackerNode when the modifier is added to a composable.
• update(): This method is called when the modifier’s parameters change. We use it to update the thresholdPercentage and onVisibilityChanged callback in the VisibilityTrackerNode.
• equals and hashCode: These methods are used to determine if two VisibilityTrackerElement are the same. We check that the thresholdPercentage and onVisibilityChanged are the same.
• InspectorInfo.inspectableProperties: This method allow the inspection of this modifier from the inspector tool.

Step 4: Create the Modifier Extension

• Modifier.trackVisibility: This is a simple extension on Modifier.
• this then VisibilityTrackerElement(…): This is the crucial line. It’s how we link our VisibilityTrackerElement to the modifier chain.

Step 5: Using the Modifier

Now, let’s see how our trackVisibility modifier can be incredibly useful in a real-world media player app.

Imagine you have a LazyColumn of video items, and you only want to play the video that’s currently visible on the screen.Here’s how we can leverage trackVisibility to achieve this efficiently:

Key Takeaways from the Node API

When implementing custom modifiers with the Node API, keep these points in mind:

1. Separation of Concerns: The `ModifierNodeElement` handles creation and configuration, while the `ModifierNode` implements the actual behaviour.

2. Performance Considerations: Be mindful of how often your callbacks are triggered. In our example, we added a threshold to avoid excessive callbacks.

3. Proper Cleanup: If your modifier allocates resources, make sure to clean them up when the node is detached.

4. Inspector Support: Implement `inspectableProperties()` to make debugging easier.

5. Immutability: The `ModifierNodeElement` should be immutable, while the `ModifierNode` can be mutable.

Conclusion

The Node API provides a powerful way to create custom modifiers in Jetpack Compose. It gives you direct access to layout information and better control over the modifier lifecycle, enabling more complex behaviours than the traditional approach.

By understanding and leveraging the Node API, you can create sophisticated custom modifiers that enhance your Compose UI in ways that weren’t possible before. Whether you’re tracking visibility, implementing custom layouts, or adding complex interactions, the Node API gives you the tools you need to build powerful, reusable UI components.

Remember that while the Node API is more powerful, it’s also more complex. For simple modifiers, the traditional approach might still be sufficient. Choose the right tool for the job based on your specific requirements.

Happy composing!

— -

This article is a continuation of Custom Modifiers in Jetpack Compose. If you’re new to custom modifiers, I recommend reading that article first to understand the basics before diving into the Node API.