tessl/npm-react-native-gesture-handler
Declarative API exposing platform native touch and gesture system to React Native
—
Pending
buttons.mddocs/
Button Components
High-performance button components with native feedback and gesture support for creating interactive UI elements.
Capabilities
BaseButton
Foundation button component providing core gesture handling capabilities. All other button components extend from BaseButton.
/**
* Base button component with gesture handling capabilities
* Provides core press, long press, and active state functionality
*/
function BaseButton(props: {
onPress?: (pointerInside: boolean) => void;
onLongPress?: () => void;
onActiveStateChange?: (active: boolean) => void;
delayLongPress?: number;
children?: React.ReactNode;
style?: StyleProp<ViewStyle>;
testID?: string;
accessible?: boolean;
accessibilityLabel?: string;
}): JSX.Element;
interface BaseButtonProps {
onPress?: (pointerInside: boolean) => void;
onLongPress?: () => void;
onActiveStateChange?: (active: boolean) => void;
delayLongPress?: number;
children?: React.ReactNode;
style?: StyleProp<ViewStyle>;
testID?: string;
accessible?: boolean;
accessibilityLabel?: string;
}Usage Example:
import React from "react";
import { Text } from "react-native";
import { BaseButton } from "react-native-gesture-handler";
function MyButton() {
return (
<BaseButton
onPress={(pointerInside) => {
console.log(`Button pressed, pointer inside: ${pointerInside}`);
}}
onLongPress={() => {
console.log("Button long pressed");
}}
onActiveStateChange={(active) => {
console.log(`Button active state: ${active}`);
}}
delayLongPress={800}
style={{
padding: 10,
backgroundColor: "lightblue",
borderRadius: 5,
}}
>
<Text>Press me</Text>
</BaseButton>
);
}RectButton
Rectangular button with underlay effect, ideal for list items and card-based interfaces.
/**
* Rectangular button with underlay color effect
* Shows background color change when pressed
*/
function RectButton(props: BaseButtonProps & {
underlayColor?: string;
activeOpacity?: number; // iOS only
}): JSX.Element;
interface RectButtonProps extends BaseButtonProps {
underlayColor?: string;
activeOpacity?: number; // iOS only
}Usage Example:
import React from "react";
import { Text, View } from "react-native";
import { RectButton } from "react-native-gesture-handler";
function ListItem() {
return (
<RectButton
onPress={() => console.log("List item pressed")}
underlayColor="#e0e0e0"
activeOpacity={0.8}
style={{
padding: 15,
backgroundColor: "white",
borderBottomWidth: 1,
borderBottomColor: "#f0f0f0",
}}
>
<View style={{ flexDirection: "row", alignItems: "center" }}>
<Text style={{ fontSize: 16 }}>List Item Title</Text>
</View>
</RectButton>
);
}BorderlessButton
Borderless button with opacity effect, perfect for icon buttons and minimal interfaces.
/**
* Borderless button with opacity effect
* Shows opacity change when pressed, ideal for icon buttons
*/
function BorderlessButton(props: BaseButtonProps & {
activeOpacity?: number; // iOS only
}): JSX.Element;
interface BorderlessButtonProps extends BaseButtonProps {
activeOpacity?: number; // iOS only
}Usage Example:
import React from "react";
import { Text } from "react-native";
import { BorderlessButton } from "react-native-gesture-handler";
function IconButton() {
return (
<BorderlessButton
onPress={() => console.log("Icon button pressed")}
activeOpacity={0.6}
style={{
padding: 8,
borderRadius: 20,
}}
>
<Text style={{ fontSize: 20 }}>⚙️</Text>
</BorderlessButton>
);
}RawButton
Low-level button component providing direct access to native button properties, particularly useful for Android ripple effects.
/**
* Raw native button component with platform-specific properties
* Provides direct access to native button features like Android ripple
*/
function RawButton(props: {
onPress?: (pointerInside: boolean) => void;
onLongPress?: () => void;
onActiveStateChange?: (active: boolean) => void;
delayLongPress?: number;
exclusive?: boolean;
rippleColor?: string; // Android only
rippleRadius?: number; // Android only
borderless?: boolean; // Android only
foreground?: boolean; // Android only
touchSoundDisabled?: boolean; // Android only
children?: React.ReactNode;
style?: StyleProp<ViewStyle>;
testID?: string;
}): JSX.Element;
interface RawButtonProps {
onPress?: (pointerInside: boolean) => void;
onLongPress?: () => void;
onActiveStateChange?: (active: boolean) => void;
delayLongPress?: number;
exclusive?: boolean;
rippleColor?: string; // Android only
rippleRadius?: number; // Android only
borderless?: boolean; // Android only
foreground?: boolean; // Android only
touchSoundDisabled?: boolean; // Android only
children?: React.ReactNode;
style?: StyleProp<ViewStyle>;
testID?: string;
}Usage Example:
import React from "react";
import { Text, Platform } from "react-native";
import { RawButton } from "react-native-gesture-handler";
function AndroidRippleButton() {
return (
<RawButton
onPress={() => console.log("Raw button pressed")}
rippleColor={Platform.OS === "android" ? "rgba(0,0,0,0.2)" : undefined}
rippleRadius={Platform.OS === "android" ? 25 : undefined}
borderless={Platform.OS === "android" ? false : undefined}
foreground={Platform.OS === "android" ? true : undefined}
style={{
padding: 12,
backgroundColor: "lightgreen",
borderRadius: 6,
}}
>
<Text>Android Ripple Button</Text>
</RawButton>
);
}PureNativeButton
Alias for the native gesture handler button component, providing the purest native button experience.
/**
* Pure native button component
* Alias for the native gesture handler button implementation
*/
const PureNativeButton: typeof RawButton;Button Behavior
Press Detection
All button components provide sophisticated press detection:
- onPress: Called when the button is pressed and released
- pointerInside: Boolean parameter indicating if the pointer was inside the button bounds when released
- onLongPress: Called when the button is held for the specified duration
- onActiveStateChange: Called when the button enters or exits the active (pressed) state
Platform Differences
iOS:
activeOpacitycontrols the opacity when the button is pressed- Native UIButton-like behavior with touch feedback
- Respects iOS accessibility settings
Android:
- Ripple effects available through
rippleColor,rippleRadius,borderless, andforegroundprops - Material Design-compliant touch feedback
- Support for foreground and background ripples
Web:
- CSS-based hover and active states
- Keyboard navigation support
- Focus management for accessibility
Performance Characteristics
Button components are optimized for high performance:
- Native Thread: Press detection runs on the native UI thread
- No JavaScript Bridge: Touch events don't cross the JavaScript bridge during interaction
- Smooth Animations: Integrates seamlessly with react-native-reanimated for smooth transitions
- Memory Efficient: Minimal memory footprint for large lists of buttons
Accessibility
All button components support comprehensive accessibility:
// Accessibility props available on all button components
interface AccessibilityProps {
accessible?: boolean;
accessibilityLabel?: string;
accessibilityHint?: string;
accessibilityRole?: string;
accessibilityState?: { disabled?: boolean; selected?: boolean };
testID?: string;
}Integration with Lists
Button components are particularly well-suited for use in lists:
import React from "react";
import { FlatList, Text, View } from "react-native";
import { RectButton } from "react-native-gesture-handler";
const data = [
{ id: "1", title: "Item 1" },
{ id: "2", title: "Item 2" },
{ id: "3", title: "Item 3" },
];
function ButtonList() {
const renderItem = ({ item }) => (
<RectButton
onPress={() => console.log(`Pressed ${item.title}`)}
underlayColor="#f0f0f0"
style={{
padding: 15,
backgroundColor: "white",
borderBottomWidth: 1,
borderBottomColor: "#e0e0e0",
}}
>
<Text>{item.title}</Text>
</RectButton>
);
return (
<FlatList
data={data}
renderItem={renderItem}
keyExtractor={(item) => item.id}
/>
);
}Install with Tessl CLI
npx tessl i tessl/npm-react-native-gesture-handler