nuxt-swiftsearch

Imported from atoms-studio/nuxt-swiftsearch (skills/SKILL.md). Install upstream with npx skills add atoms-studio/nuxt-swiftsearch --skill skills. Copyright stays with the author (MIT).

Instructions

Use this skill when building search UIs in Nuxt 3 apps with Algolia via @atoms-studio/nuxt-swiftsearch.

When to Use

• Adding search functionality to a Nuxt 3 app with Algolia
• Building search pages with filters, pagination, infinite scroll
• Implementing SSR-compatible search experiences
• Migrating from vue-instantsearch to a Nuxt-native approach

Installation

npx nuxi@latest module add swiftsearch

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@atoms-studio/nuxt-swiftsearch"],
});

Core Pattern: Dual Registration

Every widget requires both a composable (in <script setup>) AND a component (in <template>). The composable registers the widget with the InstantSearch instance; the component renders it.

<template>
  <AisInstantSearch :widgets :configuration>
    <AisSearchBox />
    <AisHits />
    <AisRefinementList attribute="brand" />
  </AisInstantSearch>
</template>

<script setup lang="ts">
import { algoliasearch } from "algoliasearch";

const client = algoliasearch("APP_ID", "API_KEY");

const widgets = computed(() => [
  useAisSearchBox({}),
  useAisHits({ escapeHTML: true }),
  useAisRefinementList({ attribute: "brand" }),
]);

const configuration = ref({
  indexName: "my_index",
  searchClient: client,
});
</script>

Critical Rules

1. widgets must be computed — not a plain array. The reactivity is required for SSR hydration.
2. configuration must be ref — wrap the config object in ref().
3. Attribute props must match — when using AisRefinementList, AisMenu, etc., the attribute prop on the component must match the attribute in the composable.
4. All composables and components are auto-imported — no manual imports needed for useAis* composables or Ais* components.

Available Components & Composables

Full props, slots, composable params, and examples for every widget: widgets-reference.md

Widget Categories (Quick Lookup)

Search Input: AisSearchBox, AisAutocomplete Results: AisHits, AisInfiniteHits, AisStateResults Refinements: AisRefinementList, AisMenu, AisMenuSelect, AisHierarchicalMenu, AisNumericMenu, AisRangeInput, AisRatingMenu, AisToggleRefinement Active Filters: AisClearRefinements, AisCurrentRefinements Sorting & Pagination: AisSortBy, AisPagination Display: AisStats, AisHighlight, AisPanel Config: AisConfigure, AisQueryRuleCustomData Structure: AisInstantSearch, AisIndex

URL Routing

To sync search state with the URL:

1. Set up query string parsing:

// app/router.options.ts
import type { RouterConfig } from "@nuxt/schema";
import qs from "qs";

export default <RouterConfig>{
  parseQuery: qs.parse,
  stringifyQuery: qs.stringify,
};

2. Add the router to configuration:

<script setup lang="ts">
const algoliaRouter = useAisRouter();

const configuration = ref({
  indexName: "my_index",
  routing: algoliaRouter.value,
  searchClient: client,
});
</script>

Slot Customization

All components expose slots with typed render state:

<AisHits>
  <template #item="{ item }">
    <div>{{ item.name }}</div>
  </template>
</AisHits>

<AisInfiniteHits>
  <template #item="{ item }">
    <div>{{ item.title }}</div>
  </template>
  <template #loadMore="{ refineNext, isLastPage }">
    <button :disabled="isLastPage" @click="refineNext">Load more</button>
  </template>
</AisInfiniteHits>

Caching (Infinite Hits)

For stateful caching across page navigations:

const cache = useAisStatefulCache();
const infiniteCache = useAisInfiniteHitsStatefulCache();

const widgets = computed(() => [useAisInfiniteHits({ cache: infiniteCache })]);

Accessing the Instance

<script setup lang="ts">
const { getInstance } = useAisInstantSearch();
// Access the raw InstantSearch instance for advanced use cases
</script>

Multi-Index Search

<AisInstantSearch :widgets :configuration>
  <AisIndex index="products">
    <AisHits />
  </AisIndex>
  <AisIndex index="articles">
    <AisHits />
  </AisIndex>
</AisInstantSearch>

CSS Classes

Components use BEM convention: ais-WidgetName-element--modifier. Use useSuit("WidgetName") to generate class names programmatically.

Common Mistakes

• Forgetting to add the composable to widgets array (component renders but doesn't work)
• Using a plain array instead of computed() for widgets
• Mismatched attribute between component prop and composable param
• Importing composables manually (they're auto-imported)

Dependencies

• Nuxt >= 3.10
• algoliasearch v5+
• qs (only if using routing)