expo-tvos-search 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-02-01
+
+### Added
+- `colorScheme` prop — override the system color scheme for the search view (`'dark'`, `'light'`, or `'system'`)
+  - Fixes illegible search bar text when app has a dark background and system is in light mode
+  - Maps to `UIHostingController.overrideUserInterfaceStyle` on the native side
+  - Default `"system"` preserves existing behavior (no breaking change)
+
+### Changed
+- Search bar interactive controls (cursor, highlights) now tint to match `accentColor`
+
 ## [1.3.2] - 2026-01-25
 
 ### Added

package/README.md

@@ -1,18 +1,57 @@
-# expo-tvos-search
+# expo-tvos-search — Native tvOS Search for React Native tvOS (Expo)
 
 [![npm version](https://img.shields.io/npm/v/expo-tvos-search.svg)](https://www.npmjs.com/package/expo-tvos-search)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Test Status](https://github.com/keiver/expo-tvos-search/workflows/Test%20PR/badge.svg)](https://github.com/keiver/expo-tvos-search/actions)
 
-A native tvOS search component for Expo and React Native using SwiftUI's `.searchable` modifier. Provides the native tvOS search experience with automatic focus handling, remote control support, and flexible customization for media apps.
-
-**Platform Support:**
-- tvOS 15.0+
-- Expo SDK 51+
-- React Native tvOS 0.71+
+A native Apple TV search component built with SwiftUI's `.searchable` modifier. Drop it into your Expo tvOS app and get the system search experience — keyboard, Siri Remote, focus handling — out of the box.
+
+## Features
+
+- **Native SwiftUI** — uses `.searchable` for the real tvOS search experience, not a web imitation
+- **Siri Remote support** — full keyboard navigation, swipe, tap, and long-press handling on real hardware
+- **Configurable grid** — portrait, landscape, square, or mini cards with adjustable columns, spacing, and padding
+- **Marquee titles** — long titles auto-scroll on focus with configurable delay
+- **Image caching** — async image loading with NSCache-backed caching
+- **Title overlay** — gradient overlay with blur effect on card images, toggleable
+- **External titles** — show title and subtitle below cards instead of (or alongside) the overlay
+- **Customizable colors** — text color, accent/focus color, all via hex strings
+- **Color scheme override** — force dark or light appearance regardless of system setting
+- **Controlled search text** — set search field text programmatically for deep links, state restore, or "search for similar" flows
+- **Error & validation callbacks** — structured error events and non-fatal validation warnings
+- **Focus callbacks** — `onSearchFieldFocused` / `onSearchFieldBlurred` for gesture handler coordination
+- **Platform-safe** — renders `null` on non-tvOS platforms; use `isNativeSearchAvailable()` to gate rendering
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Prerequisites](#prerequisites-for-tvos-builds)
+- [Quick Start](#quick-start)
+- [Usage Examples](#usage-examples)
+  - [Portrait Cards](#portrait-cards)
+  - [Landscape Cards](#landscape-cards)
+  - [Mini Grid](#mini-grid)
+  - [External Titles](#external-titles)
+  - [Title Overlay Customization](#title-overlay-customization)
+  - [Layout Spacing](#layout-spacing)
+  - [Image Display Mode](#image-display-mode)
+  - [Color Scheme Override](#color-scheme-override)
+  - [Colors and Dimensions](#colors-and-dimensions)
+  - [Error Handling](#error-handling)
+  - [Apple TV Hardware Keyboard](#apple-tv-hardware-keyboard-support)
+- [API Reference](#api-reference)
+  - [Props](#props)
+  - [SearchResult](#searchresult)
+  - [Event Types](#event-types)
+  - [isNativeSearchAvailable()](#isnativesearchavailable)
+- [Result Validation](#result-validation)
+- [Demo App](#demo-app)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
 
 <p align="center">
-  <img src="screenshots/default.png" alt="expo-tvos-search fullscreen native tvOS search component" style="border-radius: 16px;max-width: 100%;"/>
+  <img src="screenshots/demo-05.webp" alt="Native tvOS search with portrait card grid showing planet results with gold accent and marquee titles" width="100%"/>
 </p>
 
 ## Installation
@@ -29,7 +68,9 @@ npx expo install github:keiver/expo-tvos-search
 
 ## Prerequisites for tvOS Builds
 
-Your project must be configured for React Native tvOS to use this module.
+Your project must be configured for React Native tvOS.
+
+**Platform requirements:** tvOS 15.0+, Expo SDK 51+, React Native tvOS 0.71+
 
 ### 1. Install react-native-tvos
 
@@ -53,167 +94,50 @@ Then add the plugin in `app.json` / `app.config.js`:
 }
 ```
 
-## Usage
-
-This example from the demo's [Portrait tab](https://github.com/keiver/expo-tvos-search-demo/blob/main/app/(tabs)/portrait.tsx) shows a complete implementation:
+## Quick Start
 
 ```tsx
-import { useState } from 'react';
-import { Alert } from 'react-native';
-import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import { LinearGradient } from 'expo-linear-gradient';
-import {
-  TvosSearchView,
-  isNativeSearchAvailable,
-  type SearchResult,
-} from 'expo-tvos-search';
-
-const PLANETS: SearchResult[] = [
+import { TvosSearchView, type SearchResult } from 'expo-tvos-search';
+
+const results: SearchResult[] = [
   {
     id: 'earth',
-    title: 'Earth - The Blue Marble of Life',
-    subtitle: 'Our home planet, the only known world to harbor life',
-    imageUrl: require('./assets/planets/earth.webp'),
+    title: 'Earth',
+    subtitle: 'The Blue Marble',
+    imageUrl: 'https://example.com/earth.jpg',
+  },
+  {
+    id: 'mars',
+    title: 'Mars',
+    subtitle: 'The Red Planet',
+    imageUrl: 'https://example.com/mars.jpg',
   },
-  // ... all planets
 ];
 
 export default function SearchScreen() {
-  const [results, setResults] = useState<SearchResult[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const insets = useSafeAreaInsets();
-
-  const handleSearch = (event: { nativeEvent: { query: string } }) => {
-    const { query } = event.nativeEvent;
-
-    if (!query.trim()) {
-      setResults([]);
-      return;
-    }
-
-    setIsLoading(true);
-
-    // Debounce dummy search (300ms)
-    setTimeout(() => {
-      const filtered = PLANETS.filter(
-        planet =>
-          planet.title.toLowerCase().includes(query.toLowerCase()) ||
-          planet.subtitle?.toLowerCase().includes(query.toLowerCase())
-      );
-      setResults(filtered);
-      setIsLoading(false);
-    }, 300);
-  };
-
-  const handleSelect = (event: { nativeEvent: { id: string } }) => {
-    const planet = PLANETS.find(p => p.id === event.nativeEvent.id);
-    if (planet) {
-      Alert.alert(planet.title, planet.subtitle);
-    }
-  };
-
-  if (!isNativeSearchAvailable()) {
-    return null; // Or show web fallback
-  }
-
   return (
-    <LinearGradient
-      colors={['#0f172a', '#1e293b', '#0f172a']}
+    <TvosSearchView
+      results={results}
+      columns={4}
+      placeholder="Search planets..."
+      isLoading={false}
+      topInset={80}
+      onSearch={(e) => console.log('Search:', e.nativeEvent.query)}
+      onSelectItem={(e) => console.log('Selected:', e.nativeEvent.id)}
+      textColor="#E5E5E5"
+      accentColor="#E50914"
+      cardWidth={280}
+      cardHeight={420}
+      overlayTitleSize={18}
       style={{ flex: 1 }}
-    >
-      <TvosSearchView
-        results={results}
-        columns={4}
-        placeholder="Search planets..."
-        isLoading={isLoading}
-        topInset={insets.top + 80}
-        onSearch={handleSearch}
-        onSelectItem={handleSelect}
-        textColor="#E5E5E5"
-        accentColor="#E50914"
-        cardWidth={280}
-        cardHeight={420}
-        overlayTitleSize={18}
-        style={{ flex: 1 }}
-      />
-    </LinearGradient>
+    />
   );
 }
 ```
 
-<p align="center">
-  <img src="screenshots/no-results.png" alt="No results for search screen using expo-tvos-search" style="border-radius: 16px;max-width: 100%;"/><br/>
-</p>
-
-## Demo App and Common Configurations
-
-Explore all configurations in the [demo app](https://github.com/keiver/expo-tvos-search-demo).
-
-### Portrait Cards
-
-```tsx
-<TvosSearchView
-  columns={4}
-  cardWidth={280}
-  cardHeight={420}
-  overlayTitleSize={18}
-  // ... other props
-/>
-```
-
-### Landscape Cards
-
-```tsx
-<TvosSearchView
-  columns={3}
-  cardWidth={500}
-  cardHeight={280}
-  // ... other props
-/>
-```
-
-### Mini Grid
-
-```tsx
-<TvosSearchView
-  columns={5}
-  cardWidth={240}
-  cardHeight={360}
-  cardMargin={60}  // v1.3.0 - extra spacing
-  // ... other props
-/>
-```
-
-### External Titles
-
-```tsx
-<TvosSearchView
-  showTitle={true}
-  showSubtitle={true}
-  showTitleOverlay={false}
-  // ... other props
-/>
-```
-
-### Error Handling
-
-```tsx
-<TvosSearchView
-  onError={(e) => {
-    const { category, message, context } = e.nativeEvent;
-    console.error(`[Search Error] ${category}: ${message}`, context);
-  }}
-  onValidationWarning={(e) => {
-    const { type, message, context } = e.nativeEvent;
-    console.warn(`[Validation] ${type}: ${message}`, context);
-  }}
-  // ... other props
-/>
-```
-
-### Apple TV Hardware Keyboard Support (v1.3.2+)
+### Apple TV Hardware Keyboard Support
 
-On real Apple TV hardware, React Native's `RCTTVRemoteHandler` installs gesture recognizers that consume Siri Remote presses before they reach SwiftUI's `.searchable` text field, which prevents keyboard input. When the search field gains focus, this component temporarily disables touch cancellation using the official `react-native-tvos` notification API, and also disables tap/long-press recognizers from parent views (to cover cases like `react-native-gesture-handler`). Swipe and pan recognizers stay active for keyboard navigation. Everything is restored when focus leaves the field. This only applies to physical devices -- the Simulator doesn't need it.
+On real Apple TV hardware, React Native's `RCTTVRemoteHandler` installs gesture recognizers that consume Siri Remote presses before they reach SwiftUI's `.searchable` text field, which prevents keyboard input. When the search field gains focus, this component temporarily disables touch cancellation using the official `react-native-tvos` notification API, and also disables tap/long-press recognizers from parent views (to cover cases like `react-native-gesture-handler`). Swipe and pan recognizers stay active for keyboard navigation. Everything is restored when focus leaves the field. This only applies to physical devices — the Simulator doesn't need it.
 
 If this interferes with gesture handling in your app, please [open an issue](https://github.com/keiver/expo-tvos-search/issues) so we can sort it out.
 
@@ -233,137 +157,140 @@ import { TVEventControl } from 'react-native';
 />
 ```
 
-### Customizing Colors and Card Dimensions
-
-```tsx
-<TvosSearchView
-  textColor="#E5E5E5"
-  accentColor="#E50914"
-  cardWidth={420}
-  cardHeight={240}
-  // ... other props
-/>
-```
-
-### Title Overlay Customization (v1.3.0+)
 
-```tsx
-<TvosSearchView
-  overlayTitleSize={22}
-  enableMarquee={true}
-  marqueeDelay={1.5}
-  // ... other props
-/>
-```
+### Color Scheme Override
 
-### Layout Spacing (v1.3.0+)
+Apps with a fixed dark background can get illegible search bar text when the system is in light mode. Use `colorScheme` to force a specific appearance:
 
 ```tsx
 <TvosSearchView
-  cardMargin={60}
-  cardPadding={25}
+  colorScheme="dark"
   // ... other props
 />
 ```
 
-### Image Display Mode
-
-```tsx
-<TvosSearchView
-  imageContentMode="fit"  // 'fill' (crop), 'fit'/'contain' (letterbox)
-  // ... other props
-/>
-```
+- `"dark"` — white text, dark UI elements (good for dark-background apps)
+- `"light"` — black text, light UI elements
+- `"system"` — follows the device setting (default, no override)
 
-<p align="center">
-  <img src="screenshots/results.png" alt="Results for search screen using expo-tvos-search" style="border-radius: 16px;max-width: 100%;"/><br/>
-</p>
+## API Reference
 
-## Props
+### Props
 
-### Core Props
+#### Core
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `results` | `SearchResult[]` | `[]` | Array of search results |
-| `columns` | `number` | `5` | Number of columns in the grid |
-| `placeholder` | `string` | `"Search..."` | Search field placeholder |
-| `searchText` | `string` | — | Programmatically set search field text (restore state, deep links) |
-| `isLoading` | `boolean` | `false` | Shows loading indicator |
+| `results` | `SearchResult[]` | `[]` | Array of search results to display. Capped at 500 items. |
+| `columns` | `number` | `5` | Number of grid columns (clamped 1–10) |
+| `placeholder` | `string` | `"Search..."` | Search field placeholder text |
+| `searchText` | `string` | — | Programmatically set search field text (for deep links, state restore) |
+| `isLoading` | `boolean` | `false` | Shows a loading indicator |
 
-### Card Dimensions & Spacing
+#### Card Dimensions & Spacing
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `cardWidth` | `number` | `280` | Width of each result card in points |
-| `cardHeight` | `number` | `420` | Height of each result card in points |
-| `cardMargin` | `number` | `40` | **(v1.3.0+)** Spacing between cards in the grid (horizontal and vertical) |
-| `cardPadding` | `number` | `16` | **(v1.3.0+)** Padding inside the card for overlay content (title/subtitle) |
-| `topInset` | `number` | `0` | Top padding (for tab bar clearance) |
+| `cardWidth` | `number` | `280` | Width of each result card in points (clamped 50–1000) |
+| `cardHeight` | `number` | `420` | Height of each result card in points (clamped 50–1000) |
+| `cardMargin` | `number` | `40` | Spacing between cards (horizontal and vertical, clamped 0–200) |
+| `cardPadding` | `number` | `16` | Padding inside the card for overlay content (clamped 0–100) |
+| `topInset` | `number` | `0` | Top padding for tab bar clearance (clamped 0–500) |
 
-### Display Options
+#### Display Options
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `showTitle` | `boolean` | `false` | Show title below each result |
+| `showTitle` | `boolean` | `false` | Show title below each result card |
 | `showSubtitle` | `boolean` | `false` | Show subtitle below title |
 | `showTitleOverlay` | `boolean` | `true` | Show title overlay with gradient at bottom of card |
 | `showFocusBorder` | `boolean` | `false` | Show border on focused item |
-| `imageContentMode` | `'fill' \| 'fit' \| 'contain'` | `'fill'` | How images fill the card: `fill` (crop to fill), `fit`/`contain` (letterbox) |
+| `imageContentMode` | `'fill' \| 'fit' \| 'contain'` | `'fill'` | How images fill the card: `fill` crops, `fit`/`contain` letterbox |
 
-### Styling & Colors
+#### Styling & Colors
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `textColor` | `string` | system default | Color for text and UI elements (hex format, e.g., "#FFFFFF") |
-| `accentColor` | `string` | `"#FFC312"` | Accent color for focused elements (hex format, e.g., "#FFC312") |
-| `overlayTitleSize` | `number` | `20` | **(v1.3.0+)** Font size for title text in the blur overlay (when showTitleOverlay is true) |
+| `textColor` | `string` | system default | Color for text and UI elements (hex, e.g. `"#FFFFFF"`) |
+| `accentColor` | `string` | `"#FFC312"` | Accent color for focused elements (hex, e.g. `"#E50914"`) |
+| `colorScheme` | `'light' \| 'dark' \| 'system'` | `"system"` | Override the system color scheme for the search view |
+| `overlayTitleSize` | `number` | `20` | Font size for title text in the blur overlay (clamped 8–72) |
 
-### Animation
+#### Animation
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `enableMarquee` | `boolean` | `true` | Enable marquee scrolling for long titles |
-| `marqueeDelay` | `number` | `1.5` | Delay in seconds before marquee starts |
+| `marqueeDelay` | `number` | `1.5` | Delay in seconds before marquee starts (clamped 0–60) |
 
-### Text Customization
+#### Text Customization
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `emptyStateText` | `string` | `"Search your library"` | Text shown when search field is empty |
 | `searchingText` | `string` | `"Searching..."` | Text shown during search |
-| `noResultsText` | `string` | `"No results found"` | Text shown when no results found |
+| `noResultsText` | `string` | `"No results found"` | Text shown when no results match |
 | `noResultsHintText` | `string` | `"Try a different search term"` | Hint text below no results message |
 
-### Event Handlers
+#### Event Handlers
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `onSearch` | `function` | required | Called when search text changes |
-| `onSelectItem` | `function` | required | Called when result is selected |
-| `onError` | `function` | optional | **(v1.2.0+)** Called when errors occur (image loading failures, validation errors) |
-| `onValidationWarning` | `function` | optional | **(v1.2.0+)** Called for non-fatal warnings (truncated fields, clamped values, invalid URLs) |
-| `onSearchFieldFocused` | `function` | optional | **(v1.3.2+)** Called when native search field gains focus. Use with `TVEventControl` for Apple TV hardware keyboard support. |
-| `onSearchFieldBlurred` | `function` | optional | **(v1.3.2+)** Called when native search field loses focus. Use to re-enable gesture handlers. |
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `onSearch` | `(event: SearchEvent) => void` | Yes | Called when search text changes |
+| `onSelectItem` | `(event: SelectItemEvent) => void` | Yes | Called when a result is selected |
+| `onError` | `(event: SearchViewErrorEvent) => void` | No | Called on errors (image loading, validation) |
+| `onValidationWarning` | `(event: ValidationWarningEvent) => void` | No | Called for non-fatal warnings (truncated fields, clamped values) |
+| `onSearchFieldFocused` | `(event: SearchFieldFocusEvent) => void` | No | Called when native search field gains focus |
+| `onSearchFieldBlurred` | `(event: SearchFieldFocusEvent) => void` | No | Called when native search field loses focus |
 
-### Other
+#### Other
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `style` | `ViewStyle` | optional | Style object for the view container |
+| `style` | `ViewStyle` | — | Style object for the view container |
 
-## Result Handling
+### SearchResult
 
-The native implementation applies the following validation and constraints:
+```ts
+interface SearchResult {
+  id: string;        // Unique identifier (used in onSelectItem)
+  title: string;     // Primary display text
+  subtitle?: string; // Optional secondary text
+  imageUrl?: string; // Optional poster/thumbnail URL (HTTPS, HTTP, or data: URI)
+}
+```
 
-- **Maximum results**: The results array is capped at 500 items. Any results beyond this limit are silently ignored.
-- **Required fields**: Results with empty `id` or `title` are automatically filtered out and not displayed.
-- **Image URL schemes**: HTTP, HTTPS, and `data:` URIs are accepted for `imageUrl`. Other URL schemes (e.g., `file://`) are rejected.
-- **HTTPS recommended**: HTTP URLs may be blocked by App Transport Security on tvOS unless explicitly allowed in Info.plist.
+### isNativeSearchAvailable()
 
-## Testing
+```ts
+function isNativeSearchAvailable(): boolean
+```
+
+Returns `true` when running on tvOS with the native module properly built. Use this to conditionally render a fallback on non-tvOS platforms.
 
-Run TypeScript tests:
+```tsx
+import { TvosSearchView, isNativeSearchAvailable } from 'expo-tvos-search';
+
+if (!isNativeSearchAvailable()) {
+  return <FallbackSearch />;
+}
+return <TvosSearchView {...props} />;
+```
+
+## Result Validation
+
+The native implementation applies the following constraints:
+
+- **Maximum results** — the array is capped at 500 items; extras are silently ignored
+- **Required fields** — results with empty `id` or `title` are filtered out
+- **Image URL schemes** — HTTP, HTTPS, and `data:` URIs are accepted; other schemes (e.g. `file://`) are rejected
+- **HTTPS recommended** — HTTP URLs may be blocked by App Transport Security unless explicitly allowed in Info.plist
+
+## Demo App
+
+Explore all configurations in the [expo-tvos-search-demo](https://github.com/keiver/expo-tvos-search-demo) repository.
+
+## Testing
 
 ```bash
 npm test                # Run tests once
@@ -373,7 +300,7 @@ npm run test:coverage   # Generate coverage report
 
 Tests cover:
 
-- `isNativeSearchAvailable()` behavior on different platforms
+- Behavior across platforms
 - Component rendering when native module is unavailable
 - Event structure validation
 
@@ -387,10 +314,25 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guid
 - Commit message conventions
 - Pull request process
 
-### Adding New Props
+<table>
+  <tr>
+    <td><img src="screenshots/default.webp" alt="Default empty search state with tvOS keyboard and tab bar" width="100%"/></td>
+    <td><img src="screenshots/demo-01.webp" alt="Square card grid layout with planet images and no title overlay" width="100%"/></td>
+    <td><img src="screenshots/demo-02.webp" alt="Four-column grid with title overlays and hardware keyboard active indicator" width="100%"/></td>
+  </tr>
+  <tr>
+    <td><img src="screenshots/demo-03.webp" alt="Five-column compact grid with short overlay titles" width="100%"/></td>
+    <td><img src="screenshots/demo-04.webp" alt="Mini card grid with truncated overlay titles on planet cards" width="100%"/></td>
+    <td><img src="screenshots/demo-06.webp" alt="Demo app home screen with feature badges and configuration menu" width="100%"/></td>
+  </tr>
+  <tr>
+    <td><img src="screenshots/no-results.webp" alt="No results found state after searching for a term with no matches" width="100%"/></td>
+    <td><img src="screenshots/results-jungle-book.webp" alt="Single search result for Jungle Book with poster card and title overlay" width="100%"/></td>
+    <td><img src="screenshots/results.webp" alt="Focused search result card for Caminandes with accent color border" width="100%"/></td>
+  </tr>
+</table>
 
-If you're adding new props to the library, follow the comprehensive checklist in [CLAUDE-adding-new-props.md](./CLAUDE-adding-new-props.md). This memory bank provides a 9-step guide ensuring props are properly wired from TypeScript through to Swift rendering.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT — see [LICENSE](LICENSE) for details.

package/build/index.d.ts

@@ -206,17 +206,34 @@ export interface TvosSearchViewProps {
      * @example "#E50914" for Netflix red
      */
     accentColor?: string;
+    /**
+     * Override the system color scheme for the search view.
+     * - `'dark'`: Force dark appearance (white text, dark UI elements)
+     * - `'light'`: Force light appearance (black text, light UI elements)
+     * - `'system'`: Follow the system appearance (default)
+     *
+     * Useful when your app has a fixed dark background and the system is in
+     * light mode, which would make search bar text illegible.
+     * @default "system"
+     */
+    colorScheme?: 'light' | 'dark' | 'system';
     /**
      * Width of each result card in points.
      * Allows customization for portrait, landscape, or square layouts.
+     * Values outside 50-1000 range are clamped.
      * @default 280
+     * @minimum 50
+     * @maximum 1000
      * @example 420 for landscape cards
      */
     cardWidth?: number;
     /**
      * Height of each result card in points.
      * Allows customization for portrait, landscape, or square layouts.
+     * Values outside 50-1000 range are clamped.
      * @default 420
+     * @minimum 50
+     * @maximum 1000
      * @example 240 for landscape cards (16:9 ratio with width=420)
      */
     cardHeight?: number;
@@ -230,20 +247,29 @@ export interface TvosSearchViewProps {
     imageContentMode?: 'fill' | 'fit' | 'contain';
     /**
      * Spacing between cards in the grid layout (both horizontal and vertical).
+     * Values outside 0-200 range are clamped.
      * @default 40
+     * @minimum 0
+     * @maximum 200
      * @example 60 for spacious layouts, 20 for compact grids
      */
     cardMargin?: number;
     /**
      * Padding inside the card for overlay content (title, subtitle).
+     * Values outside 0-100 range are clamped.
      * @default 16
+     * @minimum 0
+     * @maximum 100
      * @example 20 for more breathing room, 12 for compact cards
      */
     cardPadding?: number;
     /**
      * Font size for title in the blur overlay (when showTitleOverlay is true).
      * Allows customization of overlay text size for different card layouts.
+     * Values outside 8-72 range are clamped.
      * @default 20
+     * @minimum 8
+     * @maximum 72
      * @example 18 for smaller cards, 24 for larger cards
      */
     overlayTitleSize?: number;

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}

package/ios/ExpoTvosSearch.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name           = 'ExpoTvosSearch'
-  s.version        = '1.0.0'
+  s.version        = '1.5.0'
   s.summary        = 'Native tvOS search view with SwiftUI .searchable modifier'
   s.description    = 'Provides a native tvOS search experience using SwiftUI searchable modifier for proper focus and keyboard navigation'
   s.author         = 'Keiver Hernandez'

package/ios/ExpoTvosSearchModule.swift

@@ -143,6 +143,10 @@ public class ExpoTvosSearchModule: Module {
                 view.accentColor = colorHex
             }
 
+            Prop("colorScheme") { (view: ExpoTvosSearchView, scheme: String) in
+                view.colorScheme = scheme
+            }
+
             Prop("cardWidth") { (view: ExpoTvosSearchView, width: Double) in
                 view.cardWidth = CGFloat(max(50, min(1000, width)))  // Clamp to reasonable range
             }

package/ios/ExpoTvosSearchView.swift

@@ -178,6 +178,12 @@ class ExpoTvosSearchView: ExpoView {
         }
     }
 
+    var colorScheme: String = "system" {
+        didSet {
+            applyColorScheme()
+        }
+    }
+
     var cardWidth: CGFloat = 280 {
         didSet {
             viewModel.cardWidth = cardWidth
@@ -249,12 +255,28 @@ class ExpoTvosSearchView: ExpoView {
         }
     }
 
+    private func applyColorScheme() {
+        let style: UIUserInterfaceStyle
+        switch colorScheme.lowercased() {
+        case "dark":
+            style = .dark
+        case "light":
+            style = .light
+        default:
+            style = .unspecified
+        }
+        hostingController?.overrideUserInterfaceStyle = style
+    }
+
     private func setupView() {
         let contentView = TvosSearchContentView(viewModel: viewModel)
         let controller = UIHostingController(rootView: contentView)
         controller.view.backgroundColor = .clear
         hostingController = controller
 
+        // Apply initial color scheme (default "system" → .unspecified)
+        applyColorScheme()
+
         // Configure viewModel callbacks
         viewModel.onSearch = { [weak self] query in
             self?.onSearch(["query": query])
@@ -557,6 +579,7 @@ class ExpoTvosSearchView: ExpoView {
     var noResultsText: String = "No results found"
     var noResultsHintText: String = "Try a different search term"
     var textColor: String? = nil
+    var colorScheme: String = "system"
     var accentColor: String = "#FFC312"
     var cardWidth: CGFloat = 280
     var cardHeight: CGFloat = 420

package/ios/TvosSearchContentView.swift

@@ -36,6 +36,7 @@ struct TvosSearchContentView: View {
                 viewModel.onSearch?(newValue)
             }
         }
+        .tint(viewModel.accentColor)
         .padding(.top, viewModel.topInset)
         .ignoresSafeArea(.all, edges: .top)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-tvos-search",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Native tvOS search view using SwiftUI .searchable modifier for Expo/React Native",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/index.tsx

@@ -237,10 +237,25 @@ export interface TvosSearchViewProps {
    */
   accentColor?: string;
 
+  /**
+   * Override the system color scheme for the search view.
+   * - `'dark'`: Force dark appearance (white text, dark UI elements)
+   * - `'light'`: Force light appearance (black text, light UI elements)
+   * - `'system'`: Follow the system appearance (default)
+   *
+   * Useful when your app has a fixed dark background and the system is in
+   * light mode, which would make search bar text illegible.
+   * @default "system"
+   */
+  colorScheme?: 'light' | 'dark' | 'system';
+
   /**
    * Width of each result card in points.
    * Allows customization for portrait, landscape, or square layouts.
+   * Values outside 50-1000 range are clamped.
    * @default 280
+   * @minimum 50
+   * @maximum 1000
    * @example 420 for landscape cards
    */
   cardWidth?: number;
@@ -248,7 +263,10 @@ export interface TvosSearchViewProps {
   /**
    * Height of each result card in points.
    * Allows customization for portrait, landscape, or square layouts.
+   * Values outside 50-1000 range are clamped.
    * @default 420
+   * @minimum 50
+   * @maximum 1000
    * @example 240 for landscape cards (16:9 ratio with width=420)
    */
   cardHeight?: number;
@@ -264,14 +282,20 @@ export interface TvosSearchViewProps {
 
   /**
    * Spacing between cards in the grid layout (both horizontal and vertical).
+   * Values outside 0-200 range are clamped.
    * @default 40
+   * @minimum 0
+   * @maximum 200
    * @example 60 for spacious layouts, 20 for compact grids
    */
   cardMargin?: number;
 
   /**
    * Padding inside the card for overlay content (title, subtitle).
+   * Values outside 0-100 range are clamped.
    * @default 16
+   * @minimum 0
+   * @maximum 100
    * @example 20 for more breathing room, 12 for compact cards
    */
   cardPadding?: number;
@@ -279,7 +303,10 @@ export interface TvosSearchViewProps {
   /**
    * Font size for title in the blur overlay (when showTitleOverlay is true).
    * Allows customization of overlay text size for different card layouts.
+   * Values outside 8-72 range are clamped.
    * @default 20
+   * @minimum 8
+   * @maximum 72
    * @example 18 for smaller cards, 24 for larger cards
    */
   overlayTitleSize?: number;