react-native-cli-hold-menu
v1.0.1
Published
A performant, easy to use hold to open context menu for React Native Cli.
Downloads
17
Maintainers
Readme
React Native Cli Hold Menu
A performant, easy-to-use hold to open a context menu for React Native Cli 🔥
Features
- Smooth interactions & animations.
- Supports dark/light Mode. 🌚 🌝
- Supports device orientation change.
- Compatible with Cli.
- Written in
TypeScript
.
Getting Started
- id: getting-started
- title: Getting Started
- Description: A performant, easy-to-use hold to open the context menu for React Native Cli 🔥
- hide_title: true
- slug: /
- hide_table_of_contents: true
Installation
yarn add react-native-cli-hold-menu
Dependencies
This library needs these dependencies to be installed in your project before you can use it:
yarn add react-native-reanimated react-native-gesture-handler react-native-unimodules @react-native-community/blur react-native-haptic-feedback
React Native Gesture Handler needs extra steps to finalize its installation, please follow their installation instructions.
React Native Reanimated needs extra steps to finalize its installation, please follow their installation instructions.
id: props title: Props slug: /props
HoldMenuProvider
iconComponent
If you want to use an icon in your menu items, you need to set your Icon component to HoldMenuProvider to be able to use it. Then you can put just the icon's name in the menu item list with the icon
prop like below.
:::note Icon can be used with just react-native-vector-icons for now. :::
import FeatherIcon from 'react-native-vector-icons/Feather';
/* ... */
<HoldMenuProvider iconComponent={FeatherIcon}>
theme
If you want to set a specific theme or change depends on your theme, use the theme
prop like below.
Values:
| value | default | | ----- | ------- | | light | true | | dark | false |
<HoldMenuProvider theme={"dark"}>
safeAreaInsets
Set object of safe area inset values to prevent the menu from being opened under the unsafe area
Example
const safeAreaInsets = useSafeAreaProvider();
<HoldMenuProvider safeAreaInsets={safeAreaInsets} />;
onOpen
Fires callback when a menu is opened
Example
const onOpen = useCallback(() => {
console.log('App onOpen')
}, []);
<HoldMenuProvider onOpen={onOpen} />;
onClose
Fires callback when a menu is opened
Example
const onClose = useCallback(() => {
console.log('App onClose')
}, []);
<HoldMenuProvider onClose={onClose} />;
HoldItem
items
An array of menu items.
| name | type | required | | ------------- | -------- | -------- | | text | string | YES | | icon | string | NO | | onPress | function | YES | | isTitle | boolean | NO | | isDestructive | boolean | NO | | withSeparator | boolean | NO |
Example
<HoldItem
items={[
{ text: 'Actions', isTitle },
{ text: 'Action 1', onPress: () => {} },
{ text: 'Action 2', isDestructive, icon: 'trash', onPress: () => {} },
]}
/>
Check out the other examples here.
actionParams
An object of keys the same name with items to match parameters to onPress actions. If you want to pass different parameters for HoldItem to menu item onPress
handlers (check example), you need to use this prop to set params per HoldItem.
The reason to provide action params with another prop is to make it able to pass with shared value without performance issues.
| type | required | | ------------------------- | -------- | | { [name: string]: any[] } | NO |
Example
const items = [
{text: 'Reply', onPress: (messageId) => {}},
{text: 'Copy', onPress: (messageText, index) => {}},
]
<HoldItem
items={items}
actionParams={{
Reply: ['dd443224-7f43'],
Copy: ['Hello World!', 1]
}}
><View/></HoldItem>
activateOn
Type of behaviour to activate menu action.
| type | default | required | | ------------------------------- | ------- | -------- | | tap double-tap hold | hold | NO |
Example
<HoldItem activateOn="double-tap" />
hapticFeedback
Type of haptic feedback behaviour.
| value | default | required | | ----------------------------------------------------------------------------------------------------------------- | -------- | -------- | | "None" "Selection" "Light" "Medium" "Heavy" "Success" "Warning" "Error" | "Medium" | NO |
Example
<HoldItem hapticFeedback="Heavy" />
menuAnchorPosition
The menu anchor position is calculated automatically. But you can override the calculation by passing an anchor position.
Auto calculation will be top-left
, top-center
or top-right
. If you want to open the menu from the bottom, you need to use
bottom-left
, bottom-center
or bottom-right
. Or if you want to use auto calculation for the bottom, see bottom
prop.
| value | required | | -------------------------------------------------------------------------------------------------------------- | -------- | | "top-center" "top-left" "top-right" "bottom-center" "bottom-left" "bottom-right" | NO |
Example
<HoldItem menuAnchorPosition="top-center" />
bottom
Hold Menu automatically calculates if you do not set menuAnchorPosition
.
If you want to open the menu from the bottom like Telegram bottom nav buttons in iOS and use auto anchor calculation,
you should set bottom
as true.
| type | default | required | | ------- | ------- | -------- | | boolean | false | NO |
Example
<HoldItem menuAnchorPosition="top-center" bottom />
disableMove
You may need to disable the move of the held item for your example. Set it true.
| type | default | required | | ------- | ------- | -------- | | boolean | false | NO |
Example
<HoldItem menuAnchorPosition="top-center" disableMove />
styles
HoldItem
container styles. You may need dynamic width or hight for some examples like message boxes. See the Whatsapp example.
| type | default | required | | ------------------------ | ------- | -------- | | ViewStyle | ViewStyle[] | {} | NO |
Example
// For Whatsapp example
<HoldItem
styles={{
position: 'relative',
maxWidth: '80%',
}}
/>
closeOnTap
Set true if you want to close the menu when tapping to HoldItem
| type | default | required | | ------- | ------- | -------- | | boolean | false | NO |
Example
<HoldItem closeOnTap />
longPressMinDurationMs
Set the delay before a long tap will activate the gesture. May be useful to increase this value in lists
| type | default | required | | ------- | ------- | -------- | | number | 150 | NO |
Example
<HoldItem longPressMinDurationMs={250} />
USAGE
id: usage title: Usage slug: /usage hide_table_of_contents: true hide_title: true
HoldMenuProvider
Before using Hold Menu in your application, you need to wrap your app with HoldMenuProvider
first.
See all the HoldMenuProvider props.
import React from 'react';
import { HoldMenuProvider } from 'react-native-cli-hold-menu';
const App = () => {
return (
<HoldMenuProvider theme="light">
{/* Your app components */}
</HoldMenuProvider>
);
};
export default App;
HoldItem
Now you can wrap your components with HoldItem
. You need to set items prop and also see other optional props for your menu.
See all the HoldItem props.
import React from 'react';
import { View } from 'react-native';
import { HoldItem } from 'react-native-cli-hold-menu';
import styles from './styles';
const MenuItems = [
{ text: 'Actions', icon: 'home', isTitle: true, onPress: () => {} },
{ text: 'Action 1', icon: 'edit', onPress: () => {} },
{ text: 'Action 2', icon: 'map-pin', withSeparator: true, onPress: () => {} },
{ text: 'Action 3', icon: 'trash', isDestructive: true, onPress: () => {} },
];
const Example = () => {
return (
<View style={styles.container}>
<HoldItem items={MenuItems}>
<View style={styles.item} />
</HoldItem>
<HoldItem items={MenuItems}>
<View style={styles.item} />
</HoldItem>
<HoldItem items={MenuItems} menuAnchorPosition="bottom-right">
<View style={styles.item} />
</HoldItem>
</View>
);
};
export default Example;
id: examples title: Examples slug: /examples
:::info If you want to see full examples in your phone or simulator, you can clone this showcase project and run 🔥 :::
Configuring List
Sample List
Code
<HoldItem
items={[
{ text: 'Reply', onPress: () => {} },
{ text: 'Edit', onPress: () => {} },
{ text: 'Delete', onPress: () => {} },
]}
/>
Result
List with title
Code
<HoldItem
items={[
{ text: 'Actions', isTitle: true, onPress: () => {} },
{ text: 'Reply', onPress: () => {} },
{ text: 'Edit', onPress: () => {} },
{ text: 'Delete', onPress: () => {} },
]}
/>
Result
List with separator
Code
<HoldItem
items={[
{ text: 'Actions', isTitle: true, onPress: () => {} },
{ text: 'Reply', onPress: () => {} },
{ text: 'Edit', onPress: () => {} },
{ text: 'Delete', withSeparator: true, onPress: () => {} },
{ text: 'Share', onPress: () => {} },
]}
/>
Result
List with destructive button
Code
<HoldItem
items={[
{ text: 'Actions', isTitle: true, onPress: () => {} },
{ text: 'Reply', onPress: () => {} },
{ text: 'Edit', onPress: () => {} },
{
text: 'Delete',
withSeparator: true,
isDestructive: true,
onPress: () => {},
},
{ text: 'Share', onPress: () => {} },
]}
/>
Result
List with icons
Code
<HoldItem
items={[
{ text: 'Action', isTitle: true, onPress: () => {} },
{
text: 'Home',
icon: () => <Icon name="home" size={18} />,
onPress: () => {},
},
{
text: 'Edit',
icon: () => <Icon name="edit" size={18} />,
onPress: () => {},
},
{
text: 'Delete',
icon: () => <Icon name="delete" size={18} />,
withSeparator: true,
isDestructive: true,
onPress: () => {},
},
{
text: 'Share',
icon: () => <Icon name="share" size={18} />,
onPress: () => {},
},
{
text: 'More',
icon: () => <Icon name="more-horizontal" size={18} />,
onPress: () => {},
},
]}
/>
Result