useAisWidget

useAisWidget(connectorName, widgetId?) returns the live render-state for a connector that the parent <AisInstantSearch> already mounted.

It powers every shipped widget component (<AisRefinementList>, <AisMenu>, etc.) and is the primary extension point when you build your own.

Signature

useAisWidget<TWidget extends keyof RenderState["string"]>(
  widgetName: TWidget,
  widgetId?: string,
): {
  instance: Ref<InstantSearch>;
  state: Ref<RenderState[string][TWidget]>;
  widgetParams: ComputedRef<unknown>;
};

When to pass widgetId

• No widgetId — the composable returns the connector's bucket for the current <AisIndex> scope. Use this when there is at most one instance of the connector per index (<AisHits>, <AisStats>, single <AisRefinementList> per attribute, etc.).
• widgetId set — the composable resolves the state via provide/inject keyed by ${widgetName}-${indexScope}-${widgetId}. Use this when you mount the same connector multiple times in the same index and need each instance to keep separate state.

The id prop on the shipped components is forwarded straight to this argument.

Usage

<script setup lang="ts">
import { useAisWidget } from "#imports";

defineProps<{ id?: string }>();

const { state } = useAisWidget("hits", id);
</script>

<template>
  <ul v-if="state">
    <li v-for="hit in state.hits" :key="hit.objectID">
      {{ hit.name }}
    </li>
  </ul>
</template>

Throwing behavior

If no widget is registered for the requested connector at mount time, useAisWidget throws:

Connector for component <name> not found, did you forget to add the proper widget?

In declarative mode this is impossible; in manual mode it usually means the matching useAis*({...}, id) call is missing from the :widgets array.

Related

• Manual widgets mode — register connectors and widgets together.
• Declarative transform — automatic id injection.