EasyAppDev.Blazor.AutoComplete

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

EasyAppDev.Blazor.AutoComplete

★ 20 Open GitHub ↗

A high-performance, feature-rich AutoComplete component for Blazor applications with AI-powered semantic search capabilities

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Blazor AutoComplete Component

A high-performance, AI-powered AutoComplete (TypeAhead) component for Blazor applications with semantic search, OData integration, and vector database support. Also known as: autosuggest, combobox, searchable dropdown, live search.

[![NuGet](https://img.shields.io/nuget/v/EasyAppDev.Blazor.AutoComplete.svg)](https://www.nuget.org/packages/EasyAppDev.Blazor.AutoComplete/)
[![NuGet Downloads](https://img.shields.io/nuget/dt/EasyAppDev.Blazor.AutoComplete.svg)](https://www.nuget.org/packages/EasyAppDev.Blazor.AutoComplete/)
[![GitHub stars](https://img.shields.io/github/stars/mashrulhaque/EasyAppDev.Blazor.AutoComplete?style=social)](https://github.com/mashrulhaque/EasyAppDev.Blazor.AutoComplete)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![.NET](https://img.shields.io/badge/.NET-8.0%20%7C%209.0%20%7C%2010.0-blue)](https://dotnet.microsoft.com/)

**[Live Demo](https://blazorautocomplete.easyappdev.com/)** | [NuGet Package](https://www.nuget.org/packages/EasyAppDev.Blazor.AutoComplete/) | [Get Started](#quick-start)

---

## Why Choose This Blazor AutoComplete?

- **AI-Powered Semantic Search** - Find results by meaning, not just keywords, using OpenAI, Azure OpenAI, or any embedding provider
- **OData v3/v4 Integration** - Server-side filtering with automatic `$filter` query generation
- **5 Vector Database Providers** - PostgreSQL/pgvector, Azure AI Search, Pinecone, Qdrant, CosmosDB
- **< 15KB Gzipped** - Lightweight core with zero runtime reflection
- **Native AOT Ready** - Source generators enable full ahead-of-time compilation and trimming
- **WCAG 2.1 AA Accessible** - ARIA 1.2 combobox pattern with full keyboard navigation
- **100K+ Items** - Virtualization maintains 60fps scrolling with massive datasets
- **8 Built-in Display Modes** - Eliminate custom template boilerplate

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Features](#core-features)
  - [Multi-Field Search](#multi-field-search)
  - [Filter Strategies](#filter-strategies)
  - [Display Modes](#display-modes)
  - [Grouping](#grouping)
  - [Virtualization](#virtualization)
  - [Async Data Sources](#async-data-sources)
  - [Custom Templates](#custom-templates)
  - [Fluent Configuration API](#fluent-configuration-api)
- [Theming System](#theming-system)
  - [Theme Presets](#theme-presets)
  - [Light/Dark Mode](#lightdark-mode)
  - [Bootstrap Color Variants](#bootstrap-color-variants)
  - [Component Sizes](#component-sizes)
  - [Custom Theme Properties](#custom-theme-properties)
- [OData Integration](#odata-integration)
  - [OData Setup](#odata-setup)
  - [OData Multi-Field Search](#odata-multi-field-search)
  - [OData v3 Support](#odata-v3-support)
  - [OData Filter Strategies](#odata-filter-strategies)
  - [OData Configuration Options](#odata-configuration-options)
- [AI Semantic Search](#ai-semantic-search)
  - [Semantic Search Setup](#semantic-search-setup)
  - [SemanticAutoComplete Component](#semanticautocomplete-component)
  - [Embedding Cache System](#embedding-cache-system)
  - [Semantic Search Parameters](#semantic-search-parameters)
- [Vector Database Providers](#vector-database-providers)
  - [PostgreSQL with pgvector](#postgresql-with-pgvector)
  - [Azure AI Search](#azure-ai-search)
  - [Pinecone](#pinecone)
  - [Qdrant](#qdrant)
  - [Azure CosmosDB](#azure-cosmosdb)
  - [Indexing Data](#indexing-data)
- [Accessibility](#accessibility)
- [Security](#security)
- [API Reference](#api-reference)
- [Packages](#packages)
- [Requirements](#requirements)
- [Performance](#performance)
- [Troubleshooting](#troubleshooting)
- [Support](#support)

---

## Installation

### Core Package

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete
```

### Optional Packages

```bash
# OData server-side filtering
dotnet add package EasyAppDev.Blazor.AutoComplete.OData

# AI semantic search with embeddings
dotnet add package EasyAppDev.Blazor.AutoComplete.AI

# Vector database providers
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.PostgreSql
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.AzureSearch
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.Pinecone
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.Qdrant
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.CosmosDb
```

---

## Quick Start

### 1. Register Services

Add to `Program.cs`:

```csharp
using EasyAppDev.Blazor.AutoComplete.Extensions;

builder.Services.AddAutoComplete();
```

This registers:
- `IThemeManager` - Theme CSS generation (singleton)
- `IAutoCompleteServiceFactory` - Component service factory (singleton)

### 2. Add Styles

Add to `App.razor` or `index.html`:

```html
<head>
    <link href="_content/EasyAppDev.Blazor.AutoComplete/styles/autocomplete.base.css" rel="stylesheet" />
    <script src="_content/EasyAppDev.Blazor.AutoComplete/scripts/theme-loader.js"></script>
</head>
```

### 3. Use the Component

```razor
@using EasyAppDev.Blazor.AutoComplete

<AutoComplete TItem="Product"
              Items="@products"
              TextField="@(p => p.Name)"
              @bind-Value="@selectedProduct"
              Placeholder="Search products..." />

@code {
    private List<Product> products = new()
    {
        new Product { Id = 1, Name = "Apple", Category = "Fruits" },
        new Product { Id = 2, Name = "Banana", Category = "Fruits" },
        new Product { Id = 3, Name = "Carrot", Category = "Vegetables" }
    };
    private Product? selectedProduct;
}
```

> **Note:** The component works without `AddAutoComplete()` using fallback instances, but registering services enables proper dependency injection, testability, and singleton behavior.

---

## Core Features

### Multi-Field Search

Search across multiple properties simultaneously:

```razor
<AutoComplete TItem="Product"
              Items="@products"
              SearchFields="@(p => new[] { p.Name, p.Description, p.Category, p.SKU })"
              TextField="@(p => p.Name)"
              @bind-Value="@selectedProduct" />
```

When `SearchFields` is provided, filtering matches against all specified fields with OR logic.

### Filter Strategies

Four built-in filtering algorithms:

```razor

<AutoComplete FilterStrategy="FilterStrategy.StartsWith" ... />

<AutoComplete FilterStrategy="FilterStrategy.Contains" ... />

<AutoComplete FilterStrategy="FilterStrategy.Fuzzy" ... />

<AutoComplete FilterStrategy="FilterStrategy.Custom"
              CustomFilter="@myFilterEngine" ... />
```

**Fuzzy Search** uses Levenshtein distance algorithm with configurable tolerance for handling typos and misspellings.

### Display Modes

Eight built-in layouts eliminate custom template boilerplate:

```razor
@using EasyAppDev.Blazor.AutoComplete.Options

<AutoComplete DisplayMode="ItemDisplayMode.Simple" ... />

<AutoComplete DisplayMode="ItemDisplayMode.TitleWithDescription"
              DescriptionField="@(p => p.Category)" ... />

<AutoComplete DisplayMode="ItemDisplayMode.TitleWithBadge"
              BadgeField="@(p => $"${p.Price:F2}")"
              BadgeClass="badge bg-success" ... />

<AutoComplete DisplayMode="ItemDisplayMode.TitleDescriptionBadge"
              DescriptionField="@(p => p.Category)"
              BadgeField="@(p => p.Stock.ToString())" ... />

<AutoComplete DisplayMode="ItemDisplayMode.IconWithTitle"
              IconField="@(p => p.Emoji)" ... />

<AutoComplete DisplayMode="ItemDisplayMode.IconTitleDescription"
              IconField="@(p => p.Emoji)"
              DescriptionField="@(p => p.Category)" ... />

<AutoComplete DisplayMode="ItemDisplayMode.Card"
              IconField="@(p => p.Emoji)"
              SubtitleField="@(p => p.Category)"
              DescriptionField="@(p => p.Description)"
              BadgeField="@(p => $"${p.Price:F2}")" ... />
```

**Available modes:** `Custom`, `Simple`, `TitleWithDescription`, `TitleWithBadge`, `TitleDescriptionBadge`, `IconWithTitle`, `IconTitleDescription`, `Card`

### Grouping

Group items by category with custom headers:

```razor
<AutoComplete TItem="Product"
              Items="@products"
              GroupBy="@(p => p.Category)"
              TextField="@(p => p.Name)"
              @bind-Value="@selectedProduct">
    <GroupTemplate Context="group">
        <div class="group-header">
            <strong>@group.Key</strong>
            <span class="badge bg-secondary">@group.Count()</span>
        </div>
    </GroupTemplate>
</AutoComplete>
```

### Virtualization

Handle massive datasets with smooth 60fps scrolling:

```razor
<AutoComplete TItem="Product"
              Items="@largeDataset"
              Virtualize="true"
              VirtualizationThreshold="100"
              ItemHeight="40"
              TextField="@(p => p.Name)"
              @bind-Value="@selectedProduct" />
```

Virtualization automatically activates when item count exceeds `VirtualizationThreshold`. Tested with 100,000+ items.

### Async Data Sources

Fetch data from remote APIs:

```razor
<AutoComplete TItem="Product"
              DataSource="@dataSource"
              TextField="@(p => p.Name)"
              @bind-Value="@selectedProduct" />

@code {
    private IAutoCompleteDataSource<Product> dataSource = new RemoteDataSource<Product>(
        async (query, cancellationToken) =>
            await httpClient.GetFromJsonAsync<List<Product>>(
                $"/api/products?search={Uri.EscapeDataString(query)}",
                cancellationToken)
    );
}
```

### Custom Templates

Full control over rendering:

```razor
<AutoComplete TItem="Product"
              Items="@products"
              TextField="@(p => p.Name)"
              @bind-Value="@selectedProduct">
    <ItemTemplate Context="product">
        <div class="d-flex align-items-center gap-2">
            <img src="@product.ImageUrl" width="32" height="32" alt="@product.Name" />
            <div>
                <strong>@product.Name</strong>
                <small class="text-muted d-block">@product.Category</small>
            </div>
            <span class="ms-auto badge bg-primary">$@product.Price</span>
        </div>
    </ItemTemplate>
    <NoResultsTemplate>
        <div class="text-center py-3">
            <i class="bi bi-search"></i>
            <p>No products found</p>
        </div>
    </NoResultsTemplate>
    <LoadingTemplate>
        <div class="text-center py-3">
            <div class="spinner-border spinner-border-sm"></div>
            <span>Searching...</span>
        </div>
    </LoadingTemplate>
    <HeaderTemplate>
        <div class="dropdown-header">Select a product</div>
    </HeaderTemplate>
    <FooterTemplate>
        <div class="dropdown-footer text-muted small">
            Type to search products
        </div>
    </FooterTemplate>
</AutoComplete>
```

### Fluent Configuration API

Build complex configurations with method chaining:

```csharp
var config = AutoCompleteConfig<Product>.Create()
    .WithItems(products)
    .WithTextField(p => p.Name)
    .WithSearchFields(p => new[] { p.Name, p.Description, p.Category })
    .WithDisplayMode(ItemDisplayMode.TitleWithDescription)
    .WithTitleAndDescription(p => p.Description)
    .WithFilterStrategy(FilterStrategy.Contains)
    .WithTheme(Theme.Auto)
    .WithBootstrapTheme(BootstrapTheme.Primary)
    .WithVirtualization(threshold: 1000, itemHeight: 45)
    .WithGrouping(p => p.Category)
    .WithDebounce(300)
    .Build();
```

```razor
<AutoComplete TItem="Product" Config="@config" @bind-Value="@selectedProduct" />
```

---

## Theming System

### Theme Presets

Four professional design system presets:

```razor

<AutoComplete ThemePreset="ThemePreset.Material" ... />

<AutoComplete ThemePreset="ThemePreset.Fluent" ... />

<AutoComplete ThemePreset="ThemePreset.Modern" ... />

<AutoComplete ThemePreset="ThemePreset.Bootstrap" ... />
```

### Light/Dark Mode

Automatic system preference detection:

```razor

<AutoComplete Theme="Theme.Auto" ... />

<AutoComplete Theme="Theme.Light" ... />

<AutoComplete Theme="Theme.Dark" ... />
```

### Bootstrap Color Variants

Nine Bootstrap 5 color schemes:

```razor
<AutoComplete BootstrapTheme="BootstrapTheme.Primary" ... />
<AutoComplete BootstrapTheme="BootstrapTheme.Secondary" ... />
<AutoComplete BootstrapTheme="BootstrapTheme.Success" ... />
<AutoComplete BootstrapTheme="BootstrapTheme.Danger" ... />
<AutoComplete BootstrapTheme="BootstrapTheme.Warning" ... />
<AutoComplete BootstrapTheme="BootstrapTheme.Info" ... />
<AutoComplete BootstrapTheme="BootstrapTheme.Light" ... />
<AutoComplete BootstrapTheme="BootstrapTheme.Dark" ... />
```

### Component Sizes

Three size variants:

```razor
<AutoComplete Size="ComponentSize.Compact" ... />  
<AutoComplete Size="ComponentSize.Default" ... />  
<AutoComplete Size="ComponentSize.Large" ... />    
```

### Custom Theme Properties

**Simple overrides (1-5 properties):**

```razor
<AutoComplete PrimaryColor="#FF6B6B"
              BackgroundColor="#FFFFFF"
              TextColor="#212529"
              BorderColor="#ced4da"
              BorderRadius="8px"
              FontFamily="Inter, sans-serif"
              FontSize="14px"
              DropdownShadow="0 4px 12px rgba(0,0,0,0.15)"
              ... />
```

**Structured overrides (advanced):**

```razor
<AutoComplete ThemeOverrides="@(new ThemeOptions {
    Colors = new ColorOptions {
        Primary = "#FF6B6B",
        Hover = "#f8f9fa",
        Selected = "#e9ecef"
    },
    Spacing = new SpacingOptions {
        BorderRadius = "8px",
        InputPadding = "12px 16px"
    },
    Typography = new TypographyOptions {
        FontFamily = "Inter, sans-serif",
        FontSize = "14px"
    },
    Effects = new EffectOptions {
        DropdownShadow = "0 4px 12px rgba(0,0,0,0.15)",
        TransitionDuration = "150ms"
    }
})" ... />
```

**Precedence:** Individual parameters > ThemeOverrides > Theme presets > Defaults

---

## OData Integration

The OData package enables server-side filtering with automatic `$filter` query generation for OData v3 and v4 endpoints.

### OData Setup

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete.OData
```

```razor
@using EasyAppDev.Blazor.AutoComplete
@using EasyAppDev.Blazor.AutoComplete.OData
@inject HttpClient Http

<AutoComplete TItem="Product"
              DataSource="@_odataSource"
              TextField="@(p => p.Name)"
              @bind-Value="@selectedProduct"
              Placeholder="Search products..." />

@code {
    private ODataDataSource<Product> _odataSource = null!;
    private Product? selectedProduct;

protected override void OnInitialized()
    {
        var options = new ODataOptions
        {
            EndpointUrl = "https://api.example.com/odata/Products",
            FilterStrategy = ODataFilterStrategy.StartsWith,
            Top = 20,
            CaseInsensitive = true
        };
        _odataSource = new ODataDataSource<Product>(Http, options, "Name");
    }
}
```

**Generated OData query:**
```
GET /odata/Products?$filter=startswith(tolower(Name),'apple')&$top=20
```

### OData Multi-Field Search

Search across multiple fields with OR combination:

```csharp
// Search Name, Description, and Category simultaneously
_odataSource = new ODataDataSource<Product>(
    Http,
    options,
    searchFieldNames: new[] { "Name", "Description", "Category" }
);
```

**Generated OData query:**
```
$filter=(startswith(tolower(Name),'search') or startswith(tolower(Description),'search') or startswith(tolower(Category),'search'))
```

### OData v3 Support

For legacy OData v3 endpoints:

```csharp
var options = new ODataOptions
{
    EndpointUrl = "https://legacy-api.example.com/odata/Products",
    Version = ODataVersion.V3,  // Use v3 syntax
    FilterStrategy = ODataFilterStrategy.Contains
};
```

### OData Filter Strategies

| Strategy | OData v4 | OData v3 |
|----------|----------|----------|
| `StartsWith` | `startswith(field,'value')` | `startswith(field,'value')` |
| `Contains` | `contains(field,'value')` | `substringof('value',field)` |
| `FuzzyFallback` | `contains()` + client re-rank | `substringof()` + client re-rank |

**FuzzyFallback** performs server-side contains filtering, then applies Levenshtein distance re-ranking on the client for typo tolerance.

### OData Configuration Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `EndpointUrl` | `string` | Required | OData endpoint URL |
| `Version` | `ODataVersion` | `V4` | OData protocol version (V3 or V4) |
| `FilterStrategy` | `ODataFilterStrategy` | `StartsWith` | Server-side filter type |
| `Top` | `int` | `100` | Maximum results (`$top`) |
| `Select` | `string[]?` | `null` | Fields to return (`$select`) |
| `OrderBy` | `string?` | `null` | Sort order (`$orderby`) |
| `AdditionalFilter` | `string?` | `null` | Static filter ANDed with search |
| `CaseInsensitive` | `bool` | `true` | Wrap fields with `tolower()` |
| `MinSearchLength` | `int` | `1` | Minimum characters before API call |
| `TimeoutSeconds` | `int` | `30` | HTTP request timeout |
| `CustomHeaders` | `Dictionary<string,string>?` | `null` | HTTP headers (Authorization, etc.) |
| `ResultsPropertyName` | `string` | `"value"` | JSON property containing results array |
| `IncludeCount` | `bool` | `false` | Include `$count` in response |

### OData with Fluent Builder

```csharp
var config = AutoCompleteConfig<Product>.Create()
    .WithODataSource(Http, "https://api.example.com/odata/Products", "Name",
        opts => {
            opts.FilterStrategy = ODataFilterStrategy.Contains;
            opts.Top = 25;
            opts.OrderBy = "Name asc";
            opts.AdditionalFilter = "IsActive eq true";
        })
    .WithDisplayMode(ItemDisplayMode.TitleWithDescription)
    .WithTitleAndDescription(p => p.Description)
    .Build();
```

### OData Service Registration

**Configuration-based:**

```json
// appsettings.json
{
  "ODataSettings": {
    "EndpointUrl": "https://api.example.com/odata/Products",
    "FilterStrategy": "Contains",
    "Top": 50
  }
}
```

```csharp
builder.Services.AddAutoCompleteOData(builder.Configuration, "ODataSettings");
```

**Explicit configuration:**

```csharp
builder.Services.AddAutoCompleteOData(
    "https://api.example.com/odata/Products",
    options => {
        options.FilterStrategy = ODataFilterStrategy.Contains;
        options.Top = 50;
        options.CustomHeaders = new Dictionary<string, string>
        {
            ["Authorization"] = "Bearer your-token"
        };
    });
```

---

## AI Semantic Search

The AI package enables meaning-based search using text embeddings and vector similarity. Find "automobile" when searching for "car".

### Semantic Search Setup

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete.AI
```

**OpenAI Configuration:**

```csharp
// Using appsettings.json
builder.Services.AddAutoCompleteSemanticSearch(builder.Configuration);

// Or explicit configuration
builder.Services.AddAutoCompleteSemanticSearch(
    apiKey: "sk-...",
    model: "text-embedding-3-small"  // Default model
);
```

```json
// appsettings.json
{
  "OpenAI": {
    "ApiKey": "sk-...",
    "Model": "text-embedding-3-small"
  }
}
```

**Azure OpenAI Configuration:**

```csharp
builder.Services.AddAutoCompleteSemanticSearchWithAzure(
    endpoint: "https://my-resource.openai.azure.com/",
    apiKey: "your-azure-openai-key",
    deploymentName: "text-embedding-ada-002"
);
```

```json
// appsettings.json
{
  "AzureOpenAI": {
    "Endpoint": "https://my-resource.openai.azure.com/",
    "ApiKey": "your-azure-openai-key",
    "DeploymentName": "text-embedding-ada-002"
  }
}
```

### SemanticAutoComplete Component

High-level wrapper for AI-powered search:

```razor
@using EasyAppDev.Blazor.AutoComplete.AI

<SemanticAutoComplete TItem="Document"
                      Items="@documents"
                      TextField="@(d => d.Title)"
                      SearchFields="@(d => new[] { d.Title, d.Description, d.Tags })"
                      SimilarityThreshold="0.15"
                      MinSearchLength="3"
                      DebounceMs="500"
                      PreWarmCache="true"
                      ShowCacheStatus="true"
                      @bind-Value="@selectedDocument"
                      Placeholder="Search by meaning..." />

@code {
    private List<Document> documents = new();
    private Document? selectedDocument;
}
```

### Embedding Cache System

The AI package includes an intelligent dual-caching system to minimize API costs:

**Item Cache:**
- Caches embeddings for your data items
- Default TTL: 1 hour
- Default max size: 10,000 items
- LRU eviction when full

**Query Cache:**
- Caches embeddings for user search queries
- Default TTL: 15 minutes
- Default max size: 1,000 queries
- LRU eviction when full

**Pre-warming:**
```razor
<SemanticAutoComplete PreWarmCache="true" ... />
```

Generates embeddings for all items on initialization. Shows progress via `CacheWarmingProgress` event.

### Semantic Search Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `SimilarityThreshold` | `float` | `0.15` | Minimum cosine similarity (0-1) for results |
| `MinSearchLength` | `int` | `3` | Characters before semantic search triggers |
| `DebounceMs` | `int` | `500` | Delay before API call |
| `MaxResults` | `int?` | `null` | Maximum results (null = all matching) |
| `ItemCacheDuration` | `TimeSpan` | `1 hour` | Item embedding cache TTL |
| `QueryCacheDuration` | `TimeSpan` | `15 min` | Query embedding cache TTL |
| `MaxItemCacheSize` | `int` | `10,000` | Maximum cached item embeddings |
| `MaxQueryCacheSize` | `int` | `1,000` | Maximum cached query embeddings |
| `PreWarmCache` | `bool` | `false` | Generate all embeddings on init |
| `ShowCacheStatus` | `bool` | `true` | Display cache hit rate statistics |

---

## Vector Database Providers

For production deployments with persistent storage and scalable semantic search, use external vector database providers. These eliminate embedding regeneration on restart and support millions of items.

### Supported Providers

| Provider | Package | Best For |
|----------|---------|----------|
| PostgreSQL/pgvector | `EasyAppDev.Blazor.AutoComplete.AI.PostgreSql` | Self-hosted, existing Postgres infrastructure |
| Azure AI Search | `EasyAppDev.Blazor.AutoComplete.AI.AzureSearch` | Enterprise, hybrid search, managed service |
| Pinecone | `EasyAppDev.Blazor.AutoComplete.AI.Pinecone` | Serverless, automatic scaling |
| Qdrant | `EasyAppDev.Blazor.AutoComplete.AI.Qdrant` | Open-source, self-hosted, advanced filtering |
| Azure CosmosDB | `EasyAppDev.Blazor.AutoComplete.AI.CosmosDb` | Global distribution, multi-model |

### PostgreSQL with pgvector

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.PostgreSql
```

**Configuration:**

```json
{
  "VectorSearch": {
    "PostgreSQL": {
      "ConnectionString": "Host=localhost;Database=myapp;Username=user;Password=pass",
      "CollectionName": "products",
      "EmbeddingDimensions": 1536
    }
  },
  "OpenAI": {
    "ApiKey": "sk-..."
  }
}
```

```csharp
using EasyAppDev.Blazor.AutoComplete.AI.PostgreSql.Extensions;

builder.Services.AddAutoCompletePostgres<Product>(
    builder.Configuration,
    textSelector: p => $"{p.Name} {p.Description} {p.Category}",
    idSelector: p => p.Id.ToString());

builder.Services.AddAutoCompleteVectorSearch<Product>(builder.Configuration);
```

**Features:**
- 6 distance functions (Cosine, L2, DotProduct, Manhattan, Hamming, Jaccard)
- HNSW indexing for fast approximate nearest neighbor search
- Self-hosted with your existing PostgreSQL infrastructure

### Azure AI Search

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.AzureSearch
```

**Configuration:**

```json
{
  "VectorSearch": {
    "AzureSearch": {
      "Endpoint": "https://my-search.search.windows.net",
      "ApiKey": "your-search-api-key",
      "IndexName": "products",
      "EmbeddingDimensions": 1536,
      "EnableHybridSearch": true
    }
  },
  "AzureOpenAI": {
    "Endpoint": "https://my-openai.openai.azure.com/",
    "ApiKey": "your-openai-key",
    "DeploymentName": "text-embedding-ada-002"
  }
}
```

```csharp
using EasyAppDev.Blazor.AutoComplete.AI.AzureSearch.Extensions;

builder.Services.AddAutoCompleteAzureSearch<Product>(
    builder.Configuration,
    textSelector: p => $"{p.Name} {p.Description}",
    idSelector: p => p.Id.ToString());

builder.Services.AddAutoCompleteVectorSearchWithAzure<Product>(builder.Configuration);
```

**Features:**
- Hybrid search (vector + keyword)
- Semantic ranking
- Enterprise-grade managed service

### Pinecone

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.Pinecone
```

```json
{
  "VectorSearch": {
    "Pinecone": {
      "ApiKey": "your-pinecone-api-key",
      "IndexName": "products",
      "Namespace": "default",
      "EmbeddingDimensions": 1536
    }
  }
}
```

```csharp
builder.Services.AddAutoCompletePinecone<Product>(
    builder.Configuration,
    textSelector: p => p.Name);
```

**Features:**
- Serverless architecture
- Namespace isolation
- Automatic scaling
- High availability

### Qdrant

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.Qdrant
```

```json
{
  "VectorSearch": {
    "Qdrant": {
      "Host": "localhost",
      "Port": 6334,
      "Https": false,
      "ApiKey": "your-api-key-for-cloud",
      "CollectionName": "products",
      "EmbeddingDimensions": 1536
    }
  }
}
```

```csharp
builder.Services.AddAutoCompleteQdrant<Product>(
    builder.Configuration,
    textSelector: p => p.Name);
```

**Features:**
- Open-source
- Self-hosted or cloud
- Advanced filtering with payload
- HNSW indexing

### Azure CosmosDB

```bash
dotnet add package EasyAppDev.Blazor.AutoComplete.AI.CosmosDb
```

```json
{
  "VectorSearch": {
    "CosmosDb": {
      "ConnectionString": "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=...",
      "DatabaseName": "myapp",
      "ContainerName": "products",
      "EmbeddingDimensions": 1536,
      "VectorIndexType": "quantizedFlat"
    }
  }
}
```

```csharp
builder.Services.AddAutoCompleteCosmosDb<Product>(
    builder.Configuration,
    textSelector: p => p.Name);
```

**Features:**
- Multi-model database
- Global distribution
- Integrated NoSQL
- Multi-region replication

### Indexing Data

Before searching, index your data:

```csharp
public class ProductService
{
    private readonly IVectorIndexer<Product> _indexer;

public ProductService(IVectorIndexer<Product> indexer)
    {
        _indexer = indexer;
    }

public async Task IndexProductsAsync(IEnumerable<Product> products)
    {
        // Ensure collection/index exists
        await _indexer.EnsureCollectionExistsAsync();

// Index all items (with progress reporting)
        _indexer.ProgressChanged += (sender, e) =>
            Console.WriteLine($"Indexed {e.ProcessedItems}/{e.TotalItems}");

await _indexer.IndexAsync(products);
    }

public async Task IndexSingleProductAsync(Product product)
    {
        // Upsert single item
        await _indexer.IndexAsync(product);
    }
}
```

### When to Use Vector Providers

| Scenario | Recommendation |
|----------|----------------|
| Development/Prototyping | In-memory `SemanticSearchDataSource` |
| Small datasets (< 10K items) | Either approach works |
| Production (> 10K items) | Use vector provider |
| Persistence across restarts | Use vector provider |
| Multi-instance deployment | Use vector provider (shared database) |
| Hybrid search (vector + keyword) | Azure AI Search or CosmosDB |

---

## Accessibility

The component follows **WCAG 2.1 AA** guidelines and implements the **ARIA 1.2 Combobox** pattern.

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Arrow Down` | Open dropdown / Select next item |
| `Arrow Up` | Select previous item |
| `Enter` | Confirm selection |
| `Escape` | Close dropdown |
| `Home` | Jump to first item |
| `End` | Jump to last item |
| `Tab` | Close dropdown and move focus |

### ARIA Attributes

- `role="combobox"` on input
- `role="listbox"` on dropdown
- `role="option"` on items
- `aria-expanded` - Dropdown state
- `aria-activedescendant` - Current focus
- `aria-selected` - Selected item

### Screen Reader Support

```razor
<label for="product-search">Search Products:</label>
<AutoComplete InputId="product-search"
              AriaLabel="Search and select a product"
              ... />
```

### Additional Features

- **High Contrast Mode** - Respects `prefers-contrast: high`
- **Reduced Motion** - Respects `prefers-reduced-motion: reduce`
- **RTL Support** - Set `RightToLeft="true"` for right-to-left languages
- **Form Integration** - Works with Blazor `EditForm` validation

---

## Security

### Input Protection

- **CSS Sanitization** - Theme values validated against allowlists
- **Input Limits** - `MaxSearchLength` prevents memory exhaustion (default 500, max 2000)
- **ReDoS Protection** - Regex patterns use 100ms timeouts
- **OData Escaping** - Search terms properly escaped to prevent injection

### API Security

- **API Key Redaction** - Sensitive data removed from error messages and logs
- **Rate Limiting** - Token bucket algorithm protects embedding API quotas
- **Memory Pressure Monitoring** - Automatic cache eviction under memory pressure

### Configuration

```csharp
// All security limits defined in AutoCompleteConstants
public static class AutoCompleteConstants
{
    public const int DefaultMaxSearchLength = 500;
    public const int AbsoluteMaxSearchLength = 2000;
    public const int RegexTimeoutMs = 100;
    // ... more constants
}
```

---

## API Reference

### Core Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Items` | `IEnumerable<TItem>?` | `null` | Collection of items |
| `DataSource` | `IAutoCompleteDataSource<TItem>?` | `null` | Async data source (precedence over Items) |
| `Value` | `TItem?` | `null` | Selected value (two-way bindable) |
| `ValueChanged` | `EventCallback<TItem?>` | | Selection change event |
| `TextField` | `Expression<Func<TItem, string>>?` | `null` | Display text property selector |
| `SearchFields` | `Expression<Func<TItem, string[]>>?` | `null` | Multi-field search selectors |
| `Placeholder` | `string?` | `null` | Input placeholder text |
| `MinSearchLength` | `int` | `1` | Minimum characters before search |
| `MaxSearchLength` | `int` | `500` | Maximum input length |
| `MaxDisplayedItems` | `int` | `100` | Maximum items shown |
| `DebounceMs` | `int` | `300` | Debounce delay in milliseconds |
| `AllowClear` | `bool` | `true` | Show clear button |
| `Disabled` | `bool` | `false` | Disable the component |
| `CloseOnSelect` | `bool` | `true` | Close dropdown on selection |
| `Config` | `AutoCompleteConfig<TItem>?` | `null` | Fluent configuration object |

### Filtering Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `FilterStrategy` | `FilterStrategy` | `StartsWith` | Filter algorithm |
| `CustomFilter` | `IFilterEngine<TItem>?` | `null` | Custom filter implementation |

### Display Mode Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `DisplayMode` | `ItemDisplayMode` | `Custom` | Built-in display layout |
| `DescriptionField` | `Expression<Func<TItem, string>>?` | `null` | Description property |
| `BadgeField` | `Expression<Func<TItem, string>>?` | `null` | Badge property |
| `IconField` | `Expression<Func<TItem, string>>?` | `null` | Icon/emoji property |
| `SubtitleField` | `Expression<Func<TItem, string>>?` | `null` | Subtitle (Card mode) |
| `BadgeClass` | `string` | `"badge bg-primary"` | Badge CSS class |

### Theming Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Theme` | `Theme` | `Auto` | Light/Dark/Auto |
| `ThemePreset` | `ThemePreset` | `None` | Design system preset |
| `BootstrapTheme` | `BootstrapTheme` | `Default` | Bootstrap color variant |
| `Size` | `ComponentSize` | `Default` | Component size |
| `ThemeOverrides` | `ThemeOptions?` | `null` | Structured theme overrides |
| `PrimaryColor` | `string?` | `null` | Primary color override |
| `BackgroundColor` | `string?` | `null` | Background color override |
| `TextColor` | `string?` | `null` | Text color override |
| `BorderColor` | `string?` | `null` | Border color override |
| `BorderRadius` | `string?` | `null` | Border radius override |
| `FontFamily` | `string?` | `null` | Font family override |
| `FontSize` | `string?` | `null` | Font size override |
| `DropdownShadow` | `string?` | `null` | Dropdown shadow override |
| `EnableThemeTransitions` | `bool` | `true` | Enable smooth transitions |
| `RightToLeft` | `bool` | `false` | RTL text direction |

### Virtualization Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Virtualize` | `bool` | `false` | Enable virtualization |
| `VirtualizationThreshold` | `int` | `100` | Item count threshold |
| `ItemHeight` | `float` | `40` | Item height in pixels |

### Grouping Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `GroupBy` | `Expression<Func<TItem, object>>?` | `null` | Grouping property selector |
| `GroupTemplate` | `RenderFragment<IGrouping<object, TItem>>?` | `null` | Group header template |

### Template Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `ItemTemplate` | `RenderFragment<TItem>?` | Custom item rendering |
| `NoResultsTemplate` | `RenderFragment?` | No results message |
| `LoadingTemplate` | `RenderFragment?` | Loading indicator |
| `HeaderTemplate` | `RenderFragment?` | Dropdown header |
| `FooterTemplate` | `RenderFragment?` | Dropdown footer |

### Accessibility Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `AriaLabel` | `string?` | ARIA label for screen readers |
| `InputId` | `string?` | Input element ID for label association |
| `ValueExpression` | `Expression<Func<TItem?>>?` | Form validation expression |

---

## Packages

| Package | Description | Size |
|---------|-------------|------|
| `EasyAppDev.Blazor.AutoComplete` | Core component library | < 15KB gzipped |
| `EasyAppDev.Blazor.AutoComplete.Generators` | Source generators (build-time only) | 0KB runtime |
| `EasyAppDev.Blazor.AutoComplete.OData` | OData v3/v4 server-side filtering | < 5KB gzipped |
| `EasyAppDev.Blazor.AutoComplete.AI` | Semantic search with embeddings | < 25KB gzipped |
| `EasyAppDev.Blazor.AutoComplete.AI.PostgreSql` | PostgreSQL/pgvector provider | < 10KB gzipped |
| `EasyAppDev.Blazor.AutoComplete.AI.AzureSearch` | Azure AI Search provider | < 10KB gzipped |
| `EasyAppDev.Blazor.AutoComplete.AI.Pinecone` | Pinecone provider | < 10KB gzipped |
| `EasyAppDev.Blazor.AutoComplete.AI.Qdrant` | Qdrant provider | < 10KB gzipped |
| `EasyAppDev.Blazor.AutoComplete.AI.CosmosDb` | Azure CosmosDB provider | < 10KB gzipped |

---

## Requirements

- **.NET 8.0**, **.NET 9.0**, or **.NET 10.0**
- **Blazor WebAssembly**, **Blazor Server**, or **Blazor Auto/United** render modes
- Modern browser with ES6 support

---

## Performance

- **Core bundle size:** < 15KB gzipped
- **Filter 100K items:** < 100ms
- **Virtualization:** 60fps scrolling with 100K+ items
- **First render:** < 50ms
- **SIMD acceleration:** 3-5x speedup for semantic similarity calculations

---

## Troubleshooting

### Common Issues

**Component not rendering / styles missing**
```html

<link href="_content/EasyAppDev.Blazor.AutoComplete/styles/autocomplete.base.css" rel="stylesheet" />
```

**Dropdown not opening**
- Check that `Items` or `DataSource` is not null/empty
- Verify `MinSearchLength` - default is 1 character before filtering

**Items not filtering**
- Ensure `TextField` expression returns a non-null string
- Check `FilterStrategy` matches your use case (StartsWith vs Contains)

**Virtualization not working**
- Set `Virtualize="true"` explicitly
- Ensure `ItemHeight` matches your actual item height in pixels
- Check that item count exceeds `VirtualizationThreshold` (default: 100)

**OData requests failing**
- Verify `EndpointUrl` is correct and accessible
- Check CORS configuration on server
- Use browser DevTools Network tab to inspect generated OData queries

**Semantic search returning no results**
- Lower `SimilarityThreshold` (try 0.1 instead of 0.15)
- Ensure `MinSearchLength` is met (default: 3 for AI)
- Verify OpenAI/Azure API key is valid
- Check browser console for API errors

**AOT/Trimming build errors**
- Ensure you're using the latest package version
- The component is fully AOT-compatible; if issues persist, check for conflicts with other libraries

### Performance Tips

- Use `FilterStrategy.StartsWith` for fastest filtering
- Enable `Virtualize="true"` for datasets > 100 items
- Set appropriate `DebounceMs` (300-500ms) to reduce API calls
- For AI search, enable `PreWarmCache="true"` to pre-generate embeddings

---

## License

MIT License - see [LICENSE](LICENSE)

---

## Support

- [GitHub Issues](https://github.com/mashrulhaque/EasyAppDev.Blazor.AutoComplete/issues) - Bug reports and feature requests
- [GitHub Discussions](https://github.com/mashrulhaque/EasyAppDev.Blazor.AutoComplete/discussions) - Questions and community support

---

## Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

---

If you find this package useful, please consider giving it a star on GitHub!

EasyAppDev.Blazor.AutoComplete

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README