react-native-spotlight-guide
Version:
A modern, customizable and high-performance spotlight/walkthrough library for React Native with TypeScript support
219 lines (169 loc) • 6.79 kB
Markdown
# 🎯 React Native Spotlight Guide
<div align="center">
<p align="center">
A modern, customizable, and high-performance spotlight/walkthrough library for React Native
</p>
<p align="center">
<a href="https://www.npmjs.com/package/react-native-spotlight-guide">
<img src="https://img.shields.io/npm/v/react-native-spotlight-guide.svg" alt="npm version" />
</a>
<a href="https://www.npmjs.com/package/react-native-spotlight-guide">
<img src="https://img.shields.io/npm/dm/react-native-spotlight-guide.svg" alt="npm downloads" />
</a>
<a href="https://github.com/FurkanKayaDev/react-native-spotlight-guide/blob/main/LICENSE">
<img src="https://img.shields.io/npm/l/react-native-spotlight-guide.svg" alt="license" />
</a>
</p>
</div>
## 🎥 Demo
<img src="https://github.com/FurkanKayaDev/react-native-spotlight-guide/blob/main/demo/demo.gif" width="300">
## ✨ Features
- 🎨 Four spotlight shapes: rectangle, circle, oval, and custom
- 🌈 Fully customizable styles
- 📱 Native performance for iOS and Android
- 🔄 Forward/backward navigation support
- 🎭 Customizable button and content styles
- 🌓 Dark/light theme support
- 📐 Automatic positioning
- 🔧 TypeScript support
## 📦 Installation
### Requirements
- React Native >= 0.72.0
- React >= 18.2.0
- react-native-svg >= 13.0.0
## First, install the main package
```bash
# If you use npm:
npm install react-native-spotlight-guide
# Or if you use Yarn:
yarn add react-native-spotlight-guide
```
## Then, install required peer dependency
```bash
# If you use npm:
npm install react-native-svg
# Or if you use Yarn:
yarn add react-native-svg
```
## For iOS, install pods
```bash
cd ios && pod install && cd ..
```
## 🚀 Quick Start
```tsx
import { SpotlightGuide } from "react-native-spotlight-guide";
const App = () => {
const [showGuide, setShowGuide] = useState(true);
return (
<SpotlightGuide
isVisible={showGuide}
content="Welcome! This button starts the main operations."
spotlightShape="circle"
contentPosition="bottom"
onFinish={() => setShowGuide(false)}
>
<Button title="Start" onPress={() => {}} />
</SpotlightGuide>
);
};
```
## 📚 Props
### Core Props
| Prop | Type | Default | Description |
| ------------- | --------------- | ------- | ----------------------------- |
| \`children\` | React.ReactNode | - | Component to be highlighted |
| \`isVisible\` | boolean | false | Controls spotlight visibility |
| \`content\` | string | - | Text content to be displayed |
### Appearance Props
| Prop | Type | Default | Description |
| -------------------- | --------------------------------------------- | -------------------- | --------------------------------------- |
| \`spotlightShape\` | 'circle' \| 'oval' \| 'rectangle' \| 'custom' | 'rectangle' | Shape of the spotlight |
| \`customShape\` | CustomSpotlightShape | - | Custom spotlight shape configuration |
| \`spotlightPadding\` | number | 10 | Padding between spotlight and component |
| \`overlayOpacity\` | number | 0.7 | Background overlay opacity (0-1) |
| \`overlayColor\` | string | 'rgba(0, 0, 0, 0.7)' | Background overlay color |
### Position Props
| Prop | Type | Default | Description |
| ------------------- | -------------------------------------- | -------- | ----------------------- |
| \`contentPosition\` | 'top' \| 'bottom' \| 'left' \| 'right' | 'bottom' | Position of content box |
### Style Props
| Prop | Type | Default | Description |
| ------------------------- | --------- | ------- | ----------------------- |
| \`contentContainerStyle\` | ViewStyle | - | Content container style |
| \`contentTextStyle\` | TextStyle | - | Content text style |
| \`buttonContainerStyle\` | ViewStyle | - | Button container style |
| \`buttonStyle\` | ViewStyle | - | Button style |
| \`buttonTextStyle\` | TextStyle | - | Button text style |
### Event Props
| Prop | Type | Default | Description |
| ------------------ | ---------- | ------- | --------------------------- |
| \`onNext\` | () => void | - | Next button press event |
| \`onPrev\` | () => void | - | Previous button press event |
| \`onFinish\` | () => void | - | Finish button press event |
| \`onPressOverlay\` | () => void | - | Overlay press event |
## 🎨 Customization
### Custom Shape Usage
```tsx
<SpotlightGuide
spotlightShape="custom"
customShape={{
width: 200,
height: 100,
borderRadius: 12,
backgroundColor: "rgba(0, 122, 255, 0.1)",
borderWidth: 2,
borderColor: "#007AFF",
borderStyle: "dashed",
}}
>
<YourComponent />
</SpotlightGuide>
```
### Custom Styles
```tsx
<SpotlightGuide
contentContainerStyle={{
backgroundColor: "#1E1E1E",
borderRadius: 16,
padding: 20,
shadowColor: "#000",
shadowOffset: { width: 0, height: 4 },
shadowOpacity: 0.1,
shadowRadius: 12,
elevation: 5,
}}
contentTextStyle={{
color: "#FFFFFF",
fontSize: 16,
lineHeight: 24,
textAlign: "center",
}}
buttonStyle={{
backgroundColor: "#007AFF",
paddingVertical: 12,
paddingHorizontal: 24,
borderRadius: 12,
}}
>
<YourComponent />
</SpotlightGuide>
```
## 📱 Example App
To run the example app:
```console
git clone https://github.com/FurkanKayaDev/react-native-spotlight-guide.git
cd react-native-spotlight-guide/example
yarn install
cd ios && pod install && cd ..
yarn ios # or yarn android
```
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guide](https://github.com/FurkanKayaDev/react-native-spotlight-guide/blob/main/CONTRIBUTING.md) for details.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/FurkanKayaDev/react-native-spotlight-guide/blob/main/LICENSE) file for details.
## 🙋♂️ Support
If you have any questions or suggestions, please open an issue on [GitHub Issues](https://github.com/FurkanKayaDev/react-native-spotlight-guide/issues).
---
<p align="center">
Made with ❤️ by Furkan Kaya
</p>