There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like
TextInput, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, we can wrap up these existing components for seamless integration with your React Native application.
Like the native module guide, this too is a more advanced guide that assumes you are somewhat familiar with Android SDK programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing
ImageView component available in the core React Native library.
Native views are created and manipulated by extending
ViewManager or more commonly
SimpleViewManager . A
SimpleViewManager is convenient in this case because it applies common properties such as background color, opacity, and Flexbox layout.
These subclasses are essentially singletons - only one instance of each is created by the bridge. They vend native views to the
NativeViewHierarchyManager, which delegates back to them to set and update the properties of the views as necessary. The
To vend a view:
- Create the ViewManager subclass.
- Implement the
- Expose view property setters using
- Register the manager in
createViewManagersof the applications package.
1. Create the
In this example we create view manager class
ReactImageManager that extends
SimpleViewManager of type
ReactImageView is the type of object managed by the manager, this will be the custom native view. Name returned by
2. Implement method
Views are created in the
createViewInstance method, the view should initialize itself in its default state, any properties will be set via a follow up call to
3. Expose view property setters using
@ReactPropGroup). Setter method should take view to be updated (of the current view type) as a first argument and property value as a second argument. Setter should be declared as a
void method and should be
public. Property type sent to JS is determined automatically based on the type of value argument of the setter. The following type of values are currently supported:
@ReactProp has one obligatory argument
name of type
String. Name assigned to the
@ReactProp annotation linked to the setter method is used to reference the property on JS side.
@ReactProp annotation may take following optional arguments:
defaultFloat. Those arguments should be of the corresponding type (accordingly
float) and the value provided will be passed to the setter method in case when the property that the setter is referencing has been removed from the component. Note that "default" values are only provided for primitive types, in case when setter is of some complex type,
null will be provided as a default value in case when corresponding property gets removed.
Setter declaration requirements for methods annotated with
@ReactPropGroup are different than for
@ReactProp, please refer to the
@ReactPropGroup annotation class docs for more information about it.
IMPORTANT! in ReactJS updating the property value will result in setter method call. Note that one of the ways we can update component is by removing properties that have been set before. In that case setter method will be called as well to notify view manager that property has changed. In that case "default" value will be provided (for primitive types "default" can value can be specified using
defaultFloat, etc. arguments of
@ReactProp annotation, for complex types setter will be called with value set to
4. Register the
The final Java step is to register the ViewManager to the application, this happens in a similar way to Native Modules, via the applications package member function
requireNativeComponent function takes the name of the native view. Note that if your component needs to do anything more sophisticated (e.g. custom event handling), you should wrap the native component in another React component. This is illustrated in the
MyCustomView example below.
To map the
topChange event name to the
getExportedCustomBubblingEventTypeConstants method in your
This callback is invoked with the raw event, which we typically process in the wrapper component to make a simpler API: