A customizable search engine component library for Svelte applications, powered by Google's Programmable Search Engine.
- Easy integration with Google's Custom Search Engine
- Customizable search components (Search, SearchBox, SearchResults)
- Support for both web and image search
- TypeScript support
- Reactive stores for search state management
- Customizable UI components for search results
npm install svelte-search-engine-
Set up a Google Programmable Search Engine and obtain your CX ID.
-
Add your CX ID to your environment variables:
PUBLIC_CSE_CX=your_cx_id_here- Import and use the components in your Svelte app:
<script>
import { Engine, Search } from 'svelte-search-engine';
import { PUBLIC_CSE_CX } from '$env/static/public';
</script>
<Engine cx={PUBLIC_CSE_CX}>
<Search
attributes={{
gname: 'web',
enableImageSearch: false
}}
/>
</Engine>The Engine component initializes the Google Custom Search Engine script and provides the context for other search components.
<Engine cx={YOUR_CX_ID}>
<!-- Other search components go here -->
</Engine>The Search component renders a complete search interface, including the search box and results.
<Search
attributes={{
gname: 'web',
enableImageSearch: false
}}
components={{ web: CustomResultsComponent }}
/>The SearchBox component renders only the search input field.
<SearchBox
attributes={{
gname: 'mySearchBox'
}}
/>The SearchResults component renders only the search results.
<SearchResults
attributes={{
gname: 'mySearchResults'
}}
components={{ web: CustomResultsComponent }}
/>You can customize the appearance and behavior of the search components by passing attributes and components props.
For a full list of available attributes, refer to the ComponentAttributes interface in the source code:
export interface ComponentAttributes {
/** The name of the Search Element object. */
gname?: Gname;
/** Whether to execute a search by the query embedded in the URL of the page that's loading. */
autoSearchOnLoad?: boolean;
/** Enables history management for the browser Back and Forward buttons. */
enableHistory?: boolean;
/** The query parameter name embedded in the URL. */
queryParameterName?: string;
/** The URL of the results page. */
resultsUrl?: string;
/** Whether the results page opens in a new window. */
newWindow?: boolean;
/** Allows invalid traffic-only cookies and local storage based on consent status. */
ivt?: boolean;
/** Specifies whether the mobile layout styles should be used for mobile devices. */
mobileLayout?: 'enabled' | 'disabled' | 'forced';
/** Enables autocomplete if configured in the control panel. */
enableAutoComplete?: boolean;
/** The maximum number of autocompletions to display. */
autoCompleteMaxCompletions?: number;
/** The maximum number of promotions to display in autocomplete. */
autoCompleteMaxPromotions?: number;
/** Comma-separated list of languages for which autocomplete should be enabled. */
autoCompleteValidLanguages?: string;
/** Specifies the default refinement label to display. */
defaultToRefinement?: string;
/** Specifies the style of refinements, either tab or link. */
refinementStyle?: 'tab' | 'link';
/** Enables image search if configured in the control panel. */
enableImageSearch?: boolean;
/** Specifies if the search results page will display image search results by default. */
defaultToImageSearch?: boolean;
/** Specifies the layout of the image search results page. */
imageSearchLayout?: 'classic' | 'column' | 'popup';
/** Specifies the maximum size of the search results set for image search. */
imageSearchResultSetSize?: number | string;
/** Restricts results to files of a specified extension. */
image_as_filetype?: 'jpg' | 'gif' | 'png' | 'bmp' | 'svg' | 'webp' | 'ico' | 'raw';
/** Filters search results using Logical OR. */
image_as_oq?: string;
/** Filters based on licensing. */
image_as_rights?:
| 'cc_publicdomain'
| 'cc_attribute'
| 'cc_sharealike'
| 'cc_noncommercial'
| 'cc_nonderived';
/** Restrict results to pages from a specific site. */
image_as_sitesearch?: string;
/** Restricts search to black and white, grayscale, or color images. */
image_colortype?: 'mono' | 'gray' | 'color';
/** Restricts search results to documents originating in a particular country. */
image_cr?: string;
/** Restricts search to images of a specific dominant color. */
image_dominantcolor?:
| 'red'
| 'orange'
| 'yellow'
| 'green'
| 'teal'
| 'blue'
| 'purple'
| 'pink'
| 'white'
| 'gray'
| 'black'
| 'brown';
/** Enables or disables automatic filtering of search results. */
image_filter?: '0' | '1';
/** Boosts search results whose country of origin matches the parameter value. */
image_gl?: string;
/** Specifies the size of images returned in search results. */
image_size?: 'icon' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | 'huge';
/** Sorts results using either date or other structured content. */
image_sort_by?: '' | 'date';
/** Restricts search to images of a specific type. */
image_type?: 'clipart' | 'face' | 'lineart' | 'stock' | 'photo' | 'animated';
/** Disables web search if true. */
disableWebSearch?: boolean;
/** Extra terms added to search query using logical OR. */
webSearchQueryAddition?: string;
/** The maximum size of the web search results set. */
webSearchResultSetSize?: number | string;
/** Specifies if SafeSearch is enabled for web search results. */
webSearchSafesearch?: 'off' | 'active';
/** Restricts results to files of a specified extension. */
as_filetype?: string;
/** Filters search results using Logical OR. */
as_oq?: string;
/** Filters based on licensing. */
as_rights?:
| 'cc_publicdomain'
| 'cc_attribute'
| 'cc_sharealike'
| 'cc_noncommercial'
| 'cc_nonderived';
/** Restrict results to pages from a specific site. */
as_sitesearch?: string;
/** Restricts search results to documents originating in a particular country. */
cr?: string;
/** Enables or disables automatic filtering of search results. */
filter?: '0' | '1';
/** Boosts search results whose country of origin matches the parameter value. */
gl?: string;
/** Restricts search results to documents written in a particular language. */
lr?: string;
/** Sort results using either date or other structured content. */
sort_by?: string;
/** Enables the sorting of results by relevance, date, or label. */
enableOrderBy?: boolean;
/** Sets the link target. Default: _blank */
linkTarget?: '_blank' | '_self' | '_parent' | '_top';
/** Specifies the default text to display when no results match the query. */
noResultsString?: string;
/** The maximum size of the results set. */
resultSetSize?: number | string;
/** Specifies if SafeSearch is enabled for both web and image search. */
safeSearch?: 'off' | 'active';
}The library provides reactive stores for managing search state:
import { init, starting, ready, rendered } from 'svelte-search-engine';
init.subscribe(value => console.log('Initialization state:', value));
starting.subscribe(value => console.log('Search starting:', value));
ready.subscribe(value => console.log('Search results ready:', value));
rendered.subscribe(value => console.log('Search results rendered:', value));You can create a custom results component to display search results:
<script lang="ts">
import type { Promotion, Result } from 'svelte-search-engine';
export let promos: Promotion[] | undefined;
export let results: Result[];
</script>
<!-- Your custom results layout here -->Then use it in the Search or SearchResults component:
<Search
attributes={{ gname: 'web' }}
components={{ web: YourCustomResultsComponent }}
/>MIT
Contributions are welcome! Please feel free to submit a Pull Request.