react-native-voice-ts 1.0.0 → 1.0.2

package/README.md

@@ -15,6 +15,7 @@ A powerful, production-ready speech-to-text library for React Native application
 [Features](#-features) •
 [Installation](#-installation) •
 [Quick Start](#-quick-start) •
+[Component Usage](#-component--hook-usage) •
 [API Reference](#-api-reference) •
 [Examples](#-complete-examples) •
 [Contributing](#-contributing)
@@ -23,7 +24,7 @@ A powerful, production-ready speech-to-text library for React Native application
 
 ---
 
-## ✨ Features
+### ✨ Features
 
 ### Core Capabilities
 
@@ -43,6 +44,9 @@ A powerful, production-ready speech-to-text library for React Native application
 - 🎨 **Modern API** - Clean, intuitive API design
 - 🛡️ **Error Handling** - Comprehensive error management
 - 🔧 **Fully Customizable** - Extensive configuration options
+- 🎪 **Ready-to-use Components** - VoiceMicrophone component & useVoiceRecognition hook
+- 🔌 **Plug & Play** - Import and use instantly in any React Native app
+- 🎯 **SVG Icons Included** - Beautiful Lucide-based mic icons (MicIcon, MicOffIcon)
 
 ### Platform Support
 
@@ -98,56 +102,168 @@ cd ios && pod install && cd ..
 
 ## 🚀 Quick Start
 
-### Basic Usage
+### Three Ways to Use
 
 ```typescript
-import React, { useEffect, useState } from 'react';
-import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
-import Voice from '@react-native-voice/voice';
+// 1. Ready-to-use Component (Easiest)
+import { VoiceMicrophone } from 'react-native-voice-ts';
 
-const App = () => {
-  const [isRecording, setIsRecording] = useState(false);
-  const [recognizedText, setRecognizedText] = useState('');
+// 2. Custom Hook (More control)
+import { useVoiceRecognition } from 'react-native-voice-ts';
 
-  useEffect(() => {
-    // Set up event listeners
-    Voice.onSpeechResults = (e) => {
-      setRecognizedText(e.value[0]);
-    };
-
-    // Cleanup
-    return () => {
-      Voice.destroy().then(Voice.removeAllListeners);
-    };
-  }, []);
+// 3. Core API (Advanced)
+import Voice from 'react-native-voice-ts';
 
-  const startRecording = async () => {
-    try {
-      await Voice.start('en-US');
-      setIsRecording(true);
-    } catch (error) {
-      console.error(error);
-    }
-  };
+// 4. Import SVG Icons (Optional - for custom UI)
+import { MicIcon, MicOffIcon } from 'react-native-voice-ts';
+```
 
-  const stopRecording = async () => {
-    try {
-      await Voice.stop();
-      setIsRecording(false);
-    } catch (error) {
-      console.error(error);
-    }
-  };
+**Note:** To use SVG icons, install `react-native-svg`:
+
+```bash
+npm install react-native-svg
+# or
+yarn add react-native-svg
+```
+
+---
+
+### ⚡ Super Simple - Just Import and Use!
+
+**Example 1: Voice Search (Minimal Code)**
+
+```tsx
+import React, { useState } from 'react';
+import { View, TextInput, Button } from 'react-native';
+import { VoiceMicrophone } from 'react-native-voice-ts';
+
+export default function App() {
+  const [searchText, setSearchText] = useState('');
+
+  return (
+    <View style={{ padding: 20 }}>
+      <TextInput
+        value={searchText}
+        onChangeText={setSearchText}
+        placeholder="Type or speak..."
+      />
+
+      <VoiceMicrophone onSpeechResult={setSearchText}>
+        {({ isRecording, start, stop }) => (
+          <Button
+            onPress={isRecording ? stop : start}
+            title={isRecording ? '⏹ Stop' : '🎤 Speak'}
+          />
+        )}
+      </VoiceMicrophone>
+    </View>
+  );
+}
+```
+
+**Example 2: With Custom Styling & SVG Icons**
+
+```tsx
+import React, { useState } from 'react';
+import { View, TextInput, TouchableOpacity, StyleSheet } from 'react-native';
+import { VoiceMicrophone, MicIcon, MicOffIcon } from 'react-native-voice-ts';
+
+export default function App() {
+  const [text, setText] = useState('');
 
   return (
     <View style={styles.container}>
-      <Text style={styles.text}>{recognizedText || 'Press to speak'}</Text>
-      <TouchableOpacity
-        style={[styles.button, isRecording && styles.recording]}
-        onPress={isRecording ? stopRecording : startRecording}
-      >
-        <Text style={styles.buttonText}>
-          {isRecording ? '🔴 Stop' : '🎤 Start'}
+      <TextInput
+        style={styles.input}
+        value={text}
+        onChangeText={setText}
+        placeholder="Search..."
+      />
+
+      <VoiceMicrophone onSpeechResult={setText}>
+        {({ isRecording, start, stop }) => (
+          <TouchableOpacity
+            style={[styles.mic, isRecording && styles.recording]}
+            onPress={isRecording ? stop : start}
+          >
+            {isRecording ? (
+              <MicOffIcon size={24} color="#fff" />
+            ) : (
+              <MicIcon size={24} color="#fff" />
+            )}
+          </TouchableOpacity>
+        )}
+      </VoiceMicrophone>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flexDirection: 'row', padding: 20 },
+  input: { flex: 1, borderWidth: 1, padding: 10, marginRight: 10 },
+  mic: {
+    width: 50,
+    height: 50,
+    borderRadius: 25,
+    backgroundColor: '#007AFF',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  recording: { backgroundColor: '#FF3B30' },
+});
+```
+
+---
+
+### 🎯 Using Hook (For More Control)
+
+```tsx
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import { useVoiceRecognition } from 'react-native-voice-ts';
+
+export default function App() {
+  const { isRecording, results, start, stop } = useVoiceRecognition({
+    onResult: (text) => console.log('You said:', text),
+  });
+
+  return (
+    <View style={{ padding: 20 }}>
+      <Text>{results[0] || 'Press to speak'}</Text>
+      <Button
+        onPress={isRecording ? stop : start}
+        title={isRecording ? 'Stop' : 'Start'}
+      />
+    </View>
+  );
+}
+```
+
+---
+
+### 🔧 Advanced (Core API)
+
+```tsx
+import React, { useEffect, useState } from 'react';
+import { View, Text, Button } from 'react-native';
+import Voice from 'react-native-voice-ts';
+
+export default function App() {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    Voice.onSpeechResults = (e) => setText(e.value[0]);
+    return () => Voice.destroy().then(Voice.removeAllListeners);
+  }, []);
+
+  return (
+    <View style={{ padding: 20 }}>
+      <Text>{text}</Text>
+      <Button onPress={() => Voice.start('en-US')} title="Start" />
+      <Button onPress={() => Voice.stop()} title="Stop" />
+    </View>
+  );
+}
         </Text>
       </TouchableOpacity>
     </View>
@@ -192,7 +308,95 @@ export default App;
 
 ## 📚 API Reference
 
-### Methods
+### Components
+
+#### VoiceMicrophone
+
+A ready-to-use React component that handles all voice recognition logic.
+
+**Props:**
+
+| Prop                   | Type                      | Default   | Description                                           |
+| ---------------------- | ------------------------- | --------- | ----------------------------------------------------- |
+| `onSpeechResult`       | `(text: string) => void`  | -         | Callback when final speech result is available        |
+| `onPartialResult`      | `(text: string) => void`  | -         | Callback when partial (real-time) result is available |
+| `onStart`              | `() => void`              | -         | Callback when recording starts                        |
+| `onStop`               | `() => void`              | -         | Callback when recording stops                         |
+| `onError`              | `(error: string) => void` | -         | Callback when an error occurs                         |
+| `locale`               | `string`                  | `'en-US'` | Language locale for recognition                       |
+| `autoStart`            | `boolean`                 | `false`   | Auto-start recording on mount                         |
+| `enablePartialResults` | `boolean`                 | `true`    | Enable real-time partial results                      |
+| `children`             | `function`                | -         | Render prop function                                  |
+
+**Children Render Props:**
+
+```typescript
+{
+  isRecording: boolean; // Whether recording is active
+  recognizedText: string; // Final recognized text
+  partialText: string; // Real-time partial text
+  start: () => Promise<void>; // Start recording
+  stop: () => Promise<void>; // Stop recording
+  cancel: () => Promise<void>; // Cancel recording
+  error: string | null; // Error message if any
+}
+```
+
+**Example:**
+
+```typescript
+<VoiceMicrophone
+  locale="en-US"
+  onSpeechResult={(text) => console.log(text)}
+>
+  {({ isRecording, start, stop }) => (
+    <Button onPress={isRecording ? stop : start} />
+  )}
+</VoiceMicrophone>
+```
+
+### Hooks
+
+#### useVoiceRecognition
+
+A custom hook that provides voice recognition functionality.
+
+**Options:**
+
+| Option                 | Type                      | Default   | Description            |
+| ---------------------- | ------------------------- | --------- | ---------------------- |
+| `locale`               | `string`                  | `'en-US'` | Language locale        |
+| `enablePartialResults` | `boolean`                 | `true`    | Enable partial results |
+| `onResult`             | `(text: string) => void`  | -         | Result callback        |
+| `onError`              | `(error: string) => void` | -         | Error callback         |
+
+**Returns:**
+
+```typescript
+{
+  isRecording: boolean;
+  results: string[];
+  partialResults: string[];
+  error: string | null;
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  cancel: () => Promise<void>;
+  reset: () => void;
+}
+```
+
+**Example:**
+
+```typescript
+const { isRecording, results, start, stop } = useVoiceRecognition({
+  locale: 'en-US',
+  onResult: (text) => setSearchQuery(text),
+});
+```
+
+---
+
+### Core API Methods
 
 #### Core Methods
 
@@ -425,61 +629,688 @@ import type {
 
 ---
 
-## 💡 Complete Examples
+## 💡 More Examples
+
+### Example 1: Simple Voice Search
+
+```tsx
+import React, { useState } from 'react';
+import { View, TextInput, Button } from 'react-native';
+import { VoiceMicrophone } from 'react-native-voice-ts';
+
+function VoiceSearch() {
+  const [query, setQuery] = useState('');
+
+  return (
+    <View>
+      <TextInput
+        value={query}
+        onChangeText={setQuery}
+        placeholder="Search..."
+      />
+      <VoiceMicrophone onSpeechResult={setQuery}>
+        {({ isRecording, start, stop }) => (
+          <Button onPress={isRecording ? stop : start} title="🎤" />
+        )}
+      </VoiceMicrophone>
+    </View>
+  );
+}
+```
+
+### Example 2: Real-time Transcription
+
+```tsx
+import React, { useState } from 'react';
+import { View, Text, Button } from 'react-native';
+import { VoiceMicrophone } from 'react-native-voice-ts';
+
+function LiveTranscription() {
+  const [text, setText] = useState('');
+
+  return (
+    <View>
+      <VoiceMicrophone
+        enablePartialResults
+        onSpeechResult={setText}
+        onPartialResult={(live) => console.log('Live:', live)}
+      >
+        {({ isRecording, partialText, start, stop }) => (
+          <>
+            <Text>{isRecording ? partialText : text}</Text>
+            <Button
+              onPress={isRecording ? stop : start}
+              title={isRecording ? 'Stop' : 'Start'}
+            />
+          </>
+        )}
+      </VoiceMicrophone>
+    </View>
+  );
+}
+```
+
+### Example 3: Multi-Language
+
+```tsx
+import React, { useState } from 'react';
+import { View, Text, Button, Picker } from 'react-native';
+import { VoiceMicrophone } from 'react-native-voice-ts';
+
+function MultiLanguage() {
+  const [lang, setLang] = useState('en-US');
+  const [text, setText] = useState('');
+
+  return (
+    <View>
+      <Picker selectedValue={lang} onValueChange={setLang}>
+        <Picker.Item label="English" value="en-US" />
+        <Picker.Item label="Spanish" value="es-ES" />
+        <Picker.Item label="French" value="fr-FR" />
+      </Picker>
+
+      <Text>{text}</Text>
+
+      <VoiceMicrophone locale={lang} onSpeechResult={setText}>
+        {({ isRecording, start, stop }) => (
+          <Button onPress={isRecording ? stop : start} title="Speak" />
+        )}
+      </VoiceMicrophone>
+    </View>
+  );
+}
+```
+
+### Example 4: Voice Form
+
+```tsx
+import React, { useState } from 'react';
+import { View, TextInput, Button } from 'react-native';
+import { VoiceMicrophone } from 'react-native-voice-ts';
+
+function VoiceForm() {
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [active, setActive] = useState(null);
+
+  return (
+    <View>
+      <TextInput value={name} onChangeText={setName} placeholder="Name" />
+      <VoiceMicrophone onSpeechResult={setName}>
+        {({ isRecording, start, stop }) => (
+          <Button onPress={isRecording ? stop : start} title="🎤" />
+        )}
+      </VoiceMicrophone>
+
+      <TextInput value={email} onChangeText={setEmail} placeholder="Email" />
+      <VoiceMicrophone onSpeechResult={setEmail}>
+        {({ isRecording, start, stop }) => (
+          <Button onPress={isRecording ? stop : start} title="🎤" />
+        )}
+      </VoiceMicrophone>
+    </View>
+  );
+}
+```
+
+### Example 5: Using the Hook
+
+```tsx
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import { useVoiceRecognition } from 'react-native-voice-ts';
+
+function HookExample() {
+  const { isRecording, results, partialResults, start, stop, reset } =
+    useVoiceRecognition({
+      locale: 'en-US',
+      onResult: (text) => console.log(text),
+    });
+
+  return (
+    <View>
+      <Text>{isRecording ? partialResults[0] : results[0]}</Text>
+      <Button
+        onPress={isRecording ? stop : start}
+        title={isRecording ? 'Stop' : 'Start'}
+      />
+      <Button onPress={reset} title="Clear" />
+    </View>
+  );
+}
+```
+
+**More examples in the repo:**
+
+- [VoiceSearchExample.tsx](./example/src/VoiceSearchExample.tsx) - Full search bar implementation
+- [VoiceHookExample.tsx](./example/src/VoiceHookExample.tsx) - Hook usage with advanced features
+- [COMPONENT_USAGE.md](./COMPONENT_USAGE.md) - Comprehensive component guide
+  style={[styles.button, isRecording && styles.recording]}
+  onPress={isRecording ? stop : start} >
+  <Text style={styles.buttonText}>
+  {isRecording ? '⏹ Stop' : '🎤 Start Recording'}
+  </Text>
+  </TouchableOpacity>
+  {error && <Text style={styles.error}>{error}</Text>}
+  </View>
+  )}
+  </VoiceMicrophone>
+  </View>
+  );
+  };
+
+const styles = StyleSheet.create({
+container: {
+flex: 1,
+padding: 20,
+backgroundColor: '#f5f5f5',
+justifyContent: 'center',
+},
+title: {
+fontSize: 24,
+fontWeight: 'bold',
+textAlign: 'center',
+marginBottom: 30,
+},
+textContainer: {
+backgroundColor: '#fff',
+padding: 20,
+borderRadius: 10,
+marginBottom: 30,
+elevation: 2,
+},
+label: {
+fontSize: 12,
+color: '#666',
+marginTop: 10,
+marginBottom: 5,
+fontWeight: '600',
+},
+liveText: {
+fontSize: 16,
+color: '#007AFF',
+fontStyle: 'italic',
+},
+finalText: {
+fontSize: 18,
+color: '#000',
+fontWeight: '500',
+},
+button: {
+backgroundColor: '#007AFF',
+padding: 15,
+borderRadius: 25,
+alignItems: 'center',
+},
+recording: {
+backgroundColor: '#FF3B30',
+},
+buttonText: {
+color: '#fff',
+fontSize: 18,
+fontWeight: 'bold',
+},
+error: {
+color: '#FF3B30',
+textAlign: 'center',
+marginTop: 10,
+},
+});
+
+````
+
+### Example 3: Multi-language Voice Input
 
-For comprehensive examples including:
+```typescript
+import React, { useState } from 'react';
+import { View, Text, TouchableOpacity, StyleSheet, ScrollView } from 'react-native';
+import { VoiceMicrophone } from 'react-native-voice-ts';
+
+const MultiLanguageVoice = () => {
+  const [selectedLanguage, setSelectedLanguage] = useState('en-US');
+  const [text, setText] = useState('');
+
+  const languages = [
+    { code: 'en-US', name: 'English (US)', flag: '🇺🇸' },
+    { code: 'es-ES', name: 'Spanish', flag: '🇪🇸' },
+    { code: 'fr-FR', name: 'French', flag: '🇫🇷' },
+    { code: 'de-DE', name: 'German', flag: '🇩🇪' },
+    { code: 'zh-CN', name: 'Chinese', flag: '🇨🇳' },
+    { code: 'ja-JP', name: 'Japanese', flag: '🇯🇵' },
+  ];
 
-- Simple Voice-to-Text
-- Real-time Transcription with Partial Results
-- Multi-language Support
-- Voice Commands
-- Permission Handling
-- Custom Hooks
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Multi-language Voice Input</Text>
+
+      <ScrollView horizontal showsHorizontalScrollIndicator={false} style={styles.langScroll}>
+        {languages.map((lang) => (
+          <TouchableOpacity
+            key={lang.code}
+            style={[
+              styles.langButton,
+              selectedLanguage === lang.code && styles.selectedLang,
+            ]}
+            onPress={() => setSelectedLanguage(lang.code)}
+          >
+            <Text style={styles.flag}>{lang.flag}</Text>
+            <Text style={styles.langName}>{lang.name}</Text>
+          </TouchableOpacity>
+        ))}
+      </ScrollView>
+
+      <View style={styles.resultContainer}>
+        <Text style={styles.resultText}>{text || 'Select language and speak...'}</Text>
+      </View>
+
+      <VoiceMicrophone
+        locale={selectedLanguage}
+        onSpeechResult={setText}
+      >
+        {({ isRecording, start, stop }) => (
+          <TouchableOpacity
+            style={[styles.micButton, isRecording && styles.recording]}
+            onPress={isRecording ? stop : start}
+          >
+            <Text style={styles.micIcon}>{isRecording ? '⏹' : '🎤'}</Text>
+            <Text style={styles.micText}>
+              {isRecording ? 'Stop' : 'Start Recording'}
+            </Text>
+          </TouchableOpacity>
+        )}
+      </VoiceMicrophone>
+    </View>
+  );
+};
 
-Please refer to the [example](./example) directory in this repository.
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    backgroundColor: '#fff',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 20,
+    textAlign: 'center',
+  },
+  langScroll: {
+    marginBottom: 20,
+  },
+  langButton: {
+    padding: 10,
+    marginRight: 10,
+    borderRadius: 10,
+    backgroundColor: '#f0f0f0',
+    alignItems: 'center',
+    minWidth: 100,
+  },
+  selectedLang: {
+    backgroundColor: '#007AFF',
+  },
+  flag: {
+    fontSize: 30,
+    marginBottom: 5,
+  },
+  langName: {
+    fontSize: 12,
+  },
+  resultContainer: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: '#f9f9f9',
+    borderRadius: 10,
+    padding: 20,
+    marginBottom: 20,
+  },
+  resultText: {
+    fontSize: 18,
+    textAlign: 'center',
+  },
+  micButton: {
+    backgroundColor: '#007AFF',
+    padding: 20,
+    borderRadius: 50,
+    alignItems: 'center',
+  },
+  recording: {
+    backgroundColor: '#FF3B30',
+  },
+  micIcon: {
+    fontSize: 40,
+  },
+  micText: {
+    color: '#fff',
+    marginTop: 10,
+    fontSize: 16,
+    fontWeight: 'bold',
+  },
+});
+````
 
-### Quick Example: Custom Hook
+### Example 4: Using Custom Hook with Form Input
 
 ```typescript
-import { useEffect, useState, useCallback } from 'react';
-import Voice from '@react-native-voice/voice';
+import React, { useState } from 'react';
+import { View, TextInput, TouchableOpacity, Text, StyleSheet } from 'react-native';
+import { useVoiceRecognition } from 'react-native-voice-ts';
+
+const VoiceForm = () => {
+  const [name, setName] = useState('');
+  const [message, setMessage] = useState('');
+  const [activeField, setActiveField] = useState<'name' | 'message' | null>(null);
+
+  const { isRecording, results, start, stop } = useVoiceRecognition({
+    locale: 'en-US',
+    onResult: (text) => {
+      if (activeField === 'name') {
+        setName(text);
+      } else if (activeField === 'message') {
+        setMessage(text);
+      }
+      setActiveField(null);
+    },
+  });
+
+  const startRecordingForField = (field: 'name' | 'message') => {
+    setActiveField(field);
+    start();
+  };
 
-export const useVoiceRecognition = (locale = 'en-US') => {
-  const [isRecording, setIsRecording] = useState(false);
-  const [results, setResults] = useState<string[]>([]);
-  const [error, setError] = useState<string | null>(null);
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Voice Form</Text>
+
+      <View style={styles.inputGroup}>
+        <Text style={styles.label}>Name:</Text>
+        <View style={styles.inputRow}>
+          <TextInput
+            style={styles.input}
+            value={name}
+            onChangeText={setName}
+            placeholder="Your name"
+          />
+          <TouchableOpacity
+            style={[
+              styles.micBtn,
+              isRecording && activeField === 'name' && styles.recording,
+            ]}
+            onPress={() =>
+              isRecording ? stop() : startRecordingForField('name')
+            }
+          >
+            <Text>🎤</Text>
+          </TouchableOpacity>
+        </View>
+      </View>
+
+      <View style={styles.inputGroup}>
+        <Text style={styles.label}>Message:</Text>
+        <View style={styles.inputRow}>
+          <TextInput
+            style={[styles.input, styles.textArea]}
+            value={message}
+            onChangeText={setMessage}
+            placeholder="Your message"
+            multiline
+          />
+          <TouchableOpacity
+            style={[
+              styles.micBtn,
+              isRecording && activeField === 'message' && styles.recording,
+            ]}
+            onPress={() =>
+              isRecording ? stop() : startRecordingForField('message')
+            }
+          >
+            <Text>🎤</Text>
+          </TouchableOpacity>
+        </View>
+      </View>
 
-  useEffect(() => {
-    Voice.onSpeechStart = () => setIsRecording(true);
-    Voice.onSpeechEnd = () => setIsRecording(false);
-    Voice.onSpeechResults = (e) => setResults(e.value || []);
-    Voice.onSpeechError = (e) => setError(e.error?.message || 'Error');
-
-    return () => {
-      Voice.destroy().then(Voice.removeAllListeners);
-    };
-  }, []);
+      <TouchableOpacity
+        style={styles.submitButton}
+        onPress={() => console.log({ name, message })}
+      >
+        <Text style={styles.submitText}>Submit</Text>
+      </TouchableOpacity>
+    </View>
+  );
+};
 
-  const start = useCallback(async () => {
-    try {
-      await Voice.start(locale);
-    } catch (e) {
-      setError('Failed to start');
-    }
-  }, [locale]);
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    backgroundColor: '#fff',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 30,
+    textAlign: 'center',
+  },
+  inputGroup: {
+    marginBottom: 20,
+  },
+  label: {
+    fontSize: 16,
+    marginBottom: 8,
+    fontWeight: '600',
+  },
+  inputRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  input: {
+    flex: 1,
+    borderWidth: 1,
+    borderColor: '#ddd',
+    padding: 12,
+    borderRadius: 8,
+    marginRight: 10,
+  },
+  textArea: {
+    height: 100,
+    textAlignVertical: 'top',
+  },
+  micBtn: {
+    width: 45,
+    height: 45,
+    borderRadius: 22.5,
+    backgroundColor: '#007AFF',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  recording: {
+    backgroundColor: '#FF3B30',
+  },
+  submitButton: {
+    backgroundColor: '#34C759',
+    padding: 15,
+    borderRadius: 8,
+    alignItems: 'center',
+    marginTop: 20,
+  },
+  submitText: {
+    color: '#fff',
+    fontSize: 18,
+    fontWeight: 'bold',
+  },
+});
+```
+
+### Example 5: Voice Commands (Advanced)
 
-  const stop = useCallback(async () => {
-    try {
-      await Voice.stop();
-    } catch (e) {
-      setError('Failed to stop');
+```typescript
+import React, { useState, useEffect } from 'react';
+import { View, Text, StyleSheet, FlatList } from 'react-native';
+import { VoiceMicrophone } from 'react-native-voice-ts';
+
+const VoiceCommands = () => {
+  const [command, setCommand] = useState('');
+  const [history, setHistory] = useState<string[]>([]);
+
+  useEffect(() => {
+    if (command) {
+      handleCommand(command);
     }
-  }, []);
+  }, [command]);
+
+  const handleCommand = (text: string) => {
+    const lowerText = text.toLowerCase();
+
+    if (lowerText.includes('hello') || lowerText.includes('hi')) {
+      addToHistory('👋 Hello there!');
+    } else if (lowerText.includes('time')) {
+      addToHistory(`🕒 Current time: ${new Date().toLocaleTimeString()}`);
+    } else if (lowerText.includes('date')) {
+      addToHistory(`📅 Today's date: ${new Date().toLocaleDateString()}`);
+    } else if (lowerText.includes('clear')) {
+      setHistory([]);
+    } else {
+      addToHistory(`❓ Unknown command: "${text}"`);
+    }
+  };
+
+  const addToHistory = (message: string) => {
+    setHistory((prev) => [message, ...prev]);
+  };
 
-  return { isRecording, results, error, start, stop };
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Voice Commands</Text>
+      <Text style={styles.subtitle}>
+        Try: "Hello", "What time is it?", "What's the date?", "Clear"
+      </Text>
+
+      <VoiceMicrophone
+        onSpeechResult={setCommand}
+        autoStart={false}
+      >
+        {({ isRecording, recognizedText, start, stop }) => (
+          <View style={styles.controlPanel}>
+            <TouchableOpacity
+              style={[styles.button, isRecording && styles.recording]}
+              onPress={isRecording ? stop : start}
+            >
+              <Text style={styles.buttonText}>
+                {isRecording ? '🔴 Listening...' : '🎤 Speak Command'}
+              </Text>
+            </TouchableOpacity>
+            {recognizedText && (
+              <Text style={styles.recognizedText}>"{recognizedText}"</Text>
+            )}
+          </View>
+        )}
+      </VoiceMicrophone>
+
+      <FlatList
+        data={history}
+        style={styles.list}
+        keyExtractor={(_, index) => index.toString()}
+        renderItem={({ item }) => (
+          <View style={styles.historyItem}>
+            <Text style={styles.historyText}>{item}</Text>
+          </View>
+        )}
+        ListEmptyComponent={
+          <Text style={styles.emptyText}>No commands yet...</Text>
+        }
+      />
+    </View>
+  );
 };
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    backgroundColor: '#fff',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    textAlign: 'center',
+    marginBottom: 10,
+  },
+  subtitle: {
+    fontSize: 12,
+    color: '#666',
+    textAlign: 'center',
+    marginBottom: 20,
+  },
+  controlPanel: {
+    marginBottom: 20,
+  },
+  button: {
+    backgroundColor: '#007AFF',
+    padding: 15,
+    borderRadius: 10,
+    alignItems: 'center',
+  },
+  recording: {
+    backgroundColor: '#FF3B30',
+  },
+  buttonText: {
+    color: '#fff',
+    fontSize: 16,
+    fontWeight: 'bold',
+  },
+  recognizedText: {
+    textAlign: 'center',
+    marginTop: 10,
+    fontSize: 14,
+    color: '#666',
+    fontStyle: 'italic',
+  },
+  list: {
+    flex: 1,
+  },
+  historyItem: {
+    backgroundColor: '#f0f0f0',
+    padding: 15,
+    borderRadius: 8,
+    marginBottom: 10,
+  },
+  historyText: {
+    fontSize: 16,
+  },
+  emptyText: {
+    textAlign: 'center',
+    color: '#999',
+    marginTop: 50,
+    fontSize: 16,
+  },
+});
 ```
 
+**More examples in the repo:**
+
+- [VoiceSearchExample.tsx](./example/src/VoiceSearchExample.tsx) - Full search bar implementation
+- [VoiceHookExample.tsx](./example/src/VoiceHookExample.tsx) - Hook usage with advanced features
+- [COMPONENT_USAGE.md](./COMPONENT_USAGE.md) - Comprehensive component guide
+
+---
+
+## 📦 Component & Hook Usage
+
+### Quick Links
+
+- **[Complete Component Usage Guide](./COMPONENT_USAGE.md)** - Comprehensive guide with real-world examples
+- **[VoiceSearchExample](./example/src/VoiceSearchExample.tsx)** - Working search bar example
+- **[VoiceHookExample](./example/src/VoiceHookExample.tsx)** - Working hook usage example
+
+### Component Benefits
+
+✅ **No boilerplate** - Works out of the box  
+✅ **Automatic cleanup** - Handles all event listeners  
+✅ **Permission handling** - Built-in permission checks  
+✅ **Type-safe** - Full TypeScript support  
+✅ **Customizable** - Use your own UI with render props
+
 ---
 
 ## ⚠️ Common Issues & Solutions