Nuxt Swiftsearch
Getting Started

Declarative Transform

How Nuxt Swiftsearch compiles template widgets into connector arrays.

Nuxt Swiftsearch ships a Vite transform that converts declarative widget templates into the manual useAis* widget array expected by the SSR runtime.

What the transform does

  • Finds each <AisInstantSearch> root without an existing widgets binding.
  • Collects supported child widgets and <AisIndex> branches.
  • Injects a generated :widgets="..." computed binding.
  • Imports only the useAis* composables needed by that file.

Supported control flow

  • v-if, v-else-if, v-else branches are compiled to conditional array spreads.
  • <template v-if> wrappers are supported.
  • v-for on widget nodes (and on plain <template>/<div> wrappers around widgets) is compiled to a spread over the loop source — see Loops.

Loops (v-for)

Config-driven widget lists work declaratively:

<AisInstantSearch :configuration="configuration">
  <AisSearchBox />
  <AisRefinementList
    v-for="attribute in refinementListAttributes"
    :key="attribute"
    :attribute="attribute"
  />
</AisInstantSearch>

<script setup lang="ts">
const refinementListAttributes = ref(["brand", "price", "free_shipping"]);
</script>

The transform compiles the loop into a renderList(...) spread inside the generated widgets computed, so array/object/number/iterable sources behave exactly like template v-for. Ref sources are unwrapped automatically, and changing the source array adds/removes only the affected widgets through the normal diffing path.

Supported alias forms: item in items, (item, index) in items, (value, key, index) in object, and the of equivalents.

Loop widget ids

Each iteration gets a generated id with a per-item suffix, and the transform adds a matching :id binding to the element. The suffix comes from the :key of the v-for element:

<AisRefinementList
  v-for="attribute in attributes"
  :key="attribute"
  :attribute="attribute"
/>
<!-- the "brand" item always gets swiftsearch-1-1-brand -->

Because the id follows the item, you can remove or reorder items: the other widgets keep their ids, their refinements and their state. Use a primitive :key (a string or a number), as Vue also recommends.

Without a usable :key, the suffix is the item position, and the build warns. In that case, removing an item changes the ids of all items after it, and those widgets are created again. A :key that contains double quotes or backticks also falls back to the position.

An explicit :id inside a loop must be dynamic and unique per iteration. The transform skips a looped widget with a static id="..." and logs a build warning.

Changing the source at runtime

The loop source can grow and shrink on the client. The same applies to a widget v-if branch that turns on after the first search. On each change, the runtime compares the new widget list with the current one by widget id:

  • A new id adds the widget. Its component mounts and gets its state from a per-instance registry.
  • A missing id removes the widget. The widget removes its own refinements.
  • The same id with other params replaces the widget in place (index.updateWidget), and its UI state stays.
  • The same id with the same params changes nothing.

The refinements of all other widgets stay. The diff also continues into <AisIndex> children.

Unsupported loop shapes

These are skipped per node with a build warning (sibling widgets are still generated):

  • v-if and v-for on the same element (move the v-if to a wrapper <template> — inner v-if on widgets inside a looped wrapper is fine),
  • nested v-for loops,
  • v-for on or around <AisIndex> / <AisDynamicWidgets>,
  • destructured aliases ({ attribute } in defs — use def in defs with :attribute="def.attribute").

Ref/computed expression handling

Directive expressions used in props and conditions are normalized with automatic unref(...) support where needed.

This means ref-based props like :search-parameters="{ filters }" and branch conditions like v-if="showStats" work without manual .value access.

Automatic widget IDs

Every connector-backed widget that supports per-instance scoping receives an id:

  • when you set an explicit id="..." (or :id), that value is used and added to the corresponding useAis*({...}, id) call,
  • otherwise the transform adds a deterministic swiftsearch-N-M id to the template markup, so the component finds its widget state in the per-instance registry.

This makes it safe to render multiple instances of the same widget (for example two <AisRefinementList attribute="brand" /> blocks) without their state leaking into each other.

Sharing one connector across multiple views

Reusing the same explicit id for a widget within an <AisInstantSearch> (or within an <AisIndex> scope) deduplicates the factory call. The transform emits a single useAis*({...}, "shared-id") and every component instance with that id reads the state of that connector:

<AisInstantSearch :configuration="configuration">
  <!-- "Top of page" hits and "bottom of page" hits share one connector -->
  <AisInfiniteHits id="hits-source" :show-previous="true" />

  <!-- ...other widgets... -->

  <AisInfiniteHits id="hits-source" />
</AisInstantSearch>

Dedupe is scoped per-<AisIndex>, so the same id reused inside a different index is treated as a separate connector.

Supported declarative widgets

AisAutocomplete, AisBreadcrumb, AisClearRefinements, AisConfigure, AisCurrentRefinements, AisDynamicWidgets, AisExperimentalConfigureRelatedItems, AisExperimentalDynamicWidgets, AisHierarchicalMenu, AisHits, AisHitsPerPage, AisIndex, AisInfiniteHits, AisMenu, AisMenuSelect, AisNumericMenu, AisPagination, AisPoweredBy, AisQueryRuleContext, AisQueryRuleCustomData, AisRangeInput, AisRatingMenu, AisRefinementList, AisRelevantSort, AisSearchBox, AisSortBy, AisStats, AisToggleRefinement, AisVoiceSearch.

Widgets inside child components

By default, discovery is scoped to the file that contains <AisInstantSearch>: the transform does not look inside a child component's own template, and the build warns when it sees a component it cannot scan inside a search root.

Opt-in: childWidgetDiscovery

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

With the flag enabled, a child component containing Ais widgets is compiled into an exported widget factory parameterized by its props, and the root file imports it automatically:

<!-- pages/search.vue -->
<AisInstantSearch :configuration="configuration">
  <AisSearchBox />
  <FiltersSidebar :attributes="['brand', 'categories']" />
</AisInstantSearch>

<!-- components/FiltersSidebar.vue — widgets discovered across the file boundary -->
<template>
  <AisRefinementList v-for="attribute in attributes" :key="attribute" :attribute="attribute" />
  <AisStats />
</template>
<script setup lang="ts">
const props = defineProps<{ attributes: string[] }>();
</script>

How it works: each instance of the child receives a unique id prefix through a data-swiftsearch-id-prefix attribute (it may appear on the child's root DOM element — that's expected fallthrough), and the generated factory produces matching per-instance widget ids. Composition is fully recursive — grandchildren, v-for over child components, and v-if around them all work.

Resolution: the tag must resolve to a .vue file, either via an explicit relative import in the root file's script or via Nuxt's component auto-import registry (kebab-case and Lazy* variants included). Unresolvable tags and <component :is> keep the build warning.

What a child expression can read: the generated factory runs at module scope, outside the component. Widget expressions in a child can read:

  • the child's props (also Vue 3.5 destructured and renamed props),
  • loop aliases,
  • value imports of the child's <script setup> (refs are unwrapped).

A widget whose params read other component state (ref, computed, composables) is skipped with a build warning that names the identifier. Pass the value in as a prop, or import it from a module. Prop defaults do not apply inside the factory. The build warns when a parent does not pass a prop that the widgets read.

Imports let one shared config file drive the filters of each index, which is the pattern of issue #58:

<!-- components/IndexFilters.vue -->
<template>
  <AisRefinementList
    v-for="attribute in FILTERS[index]"
    :key="attribute"
    :attribute="attribute"
  />
</template>
<script setup lang="ts">
import { FILTERS } from "~/config/filters";
defineProps<{ index: string }>();
</script>

Caveats:

  • Server components (.server.vue / islands) are not discovered (warned specifically); .client.vue components work, with their widgets registered during SSR.
  • A static id="..." on a widget inside a child is shared across every instance of that component (warned); use a dynamic :id when instances must not share state.
  • Props named id, class, style, key, ref or prefixed data-/aria- are not forwarded to the factory — rename the prop.
  • Components from node_modules and the module's own components are never scanned.
  • Changing a child component's widgets hot-reloads the parent in dev.

With the flag off: register on the root

Without childWidgetDiscovery, register the widgets on the root — for nested layouts, the manual :widgets prop is the clearest way — and render the matching Ais* component with the same :id in the child:

<!-- pages/search.vue — widgets registered at the root -->
<template>
  <AisInstantSearch :configuration="configuration" :widgets="widgets">
    <FiltersSidebar :attributes="attributes" />
  </AisInstantSearch>
</template>

<script setup lang="ts">
const attributes = ["brand", "categories", "free_shipping"];
const widgets = computed(() =>
  attributes.map((attribute) => useAisRefinementList({ attribute }, attribute)),
);
</script>

<!-- components/FiltersSidebar.vue — renders state registered by the root -->
<template>
  <AisRefinementList
    v-for="attribute in attributes"
    :key="attribute"
    :id="attribute"
    :attribute="attribute"
  />
</template>

When the transform is skipped

  • <AisInstantSearch> already has :widgets (whole root, by design).
  • Files importing from vue-instantsearch directly (whole file).
  • Individual unsupported nodes (see Unsupported loop shapes, static id in a loop, <AisIndex> without an index, orphan v-else). Only that node is skipped — a build warning names the file, the element and the reason, and every other widget in the root is still generated. The skipped element's component will throw at runtime until you restructure it or switch the root to manual :widgets.

In all skip cases, you can keep using manual :widgets composition.

Copyright © 2026