Svelte Search Engine

A customizable search engine component library for Svelte applications, powered by Google's Programmable Search Engine.

Features

• 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

Installation

npm install svelte-search-engine

Usage

1. Set up a Google Programmable Search Engine and obtain your CX ID.

2. Add your CX ID to your environment variables:

PUBLIC_CSE_CX=your_cx_id_here

3. 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>

Components

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>

Search

The Search component renders a complete search interface, including the search box and results.

<Search
  attributes={{
    gname: 'web',
    enableImageSearch: false
  }}
  components={{ web: CustomResultsComponent }}
/>

SearchBox

The SearchBox component renders only the search input field.

<SearchBox
  attributes={{
    gname: 'mySearchBox'
  }}
/>

SearchResults

The SearchResults component renders only the search results.

<SearchResults
  attributes={{
    gname: 'mySearchResults'
  }}
  components={{ web: CustomResultsComponent }}
/>

Customization

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';
}

Stores

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));

Custom Results Component

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 }}
/>

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.