@searcly/widget/README.md

Searcly Visual Search Widget for React

# Searcly Widget

A React widget for integrating Searcly's visual search capabilities into your web applications. This widget provides a beautiful, customizable interface for users to search products by image.

## Installation

```bash
npm install @searcly/widget @searcly/sdk
# or
yarn add @searcly/widget @searcly/sdk
```

## Quick Start

```jsx
import { SearclyWidget } from '@searcly/widget';

function App() {
  return (
    <SearclyWidget
      apiKey="your_api_key_here"
      theme={{
        primaryColor: '#2af28d',
        textColor: '#000000',
        backgroundColor: '#FFFFFF',
        fontFamily: 'Inter, sans-serif'
      }}
      options={{
        showFilters: true,
        layout: 'grid',
        limit: 20
      }}
      onSearch={results => console.log('Search results:', results)}
      onError={error => console.error('Search error:', error)}
    />
  );
}
```

## Features

- Drag and drop image upload
- Customizable theme
- Grid and list view layouts
- Responsive design
- Loading states and error handling
- TypeScript support

## Props

### Required Props

| Prop | Type | Description |
|------|------|-------------|
| apiKey | string | Your Searcly API key |

### Optional Props

#### Theme Options

```typescript
interface Theme {
  primaryColor?: string;    // Default: '#2af28d'
  textColor?: string;       // Default: '#000000'
  backgroundColor?: string; // Default: '#FFFFFF'
  fontFamily?: string;      // Default: 'Inter, sans-serif'
}
```

#### Widget Options

```typescript
interface Options {
  showFilters?: boolean;           // Default: false
  layout?: 'grid' | 'list';        // Default: 'grid'
  limit?: number;                  // Default: 20
}
```

#### Event Handlers

```typescript
onSearch?: (results: any[]) => void;  // Called when search is successful
onError?: (error: Error) => void;     // Called when an error occurs
```

## Customization Examples

### Custom Theme

```jsx
<SearclyWidget
  apiKey="your_api_key"
  theme={{
    primaryColor: '#FF5733',
    textColor: '#333333',
    backgroundColor: '#F5F5F5',
    fontFamily: 'Roboto, sans-serif'
  }}
/>
```

### List Layout with Filters

```jsx
<SearclyWidget
  apiKey="your_api_key"
  options={{
    showFilters: true,
    layout: 'list',
    limit: 30
  }}
/>
```

## Development

To contribute to the widget:

1. Clone the repository
2. Install dependencies: `npm install`
3. Make your changes
4. Build: `npm run build`
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For support, email support@searcly.com or visit our [documentation](https://docs.searcly.com).