> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# useItemInstance

> Hook for accessing component instances in Weaverse Next.js components.

# useItemInstance

The `useItemInstance` hook returns a component item store. Pass an instance ID to look up a specific component, or omit it to use the current component from `WeaverseItemContext`.

## Import

```tsx theme={null}
import { useItemInstance } from '@weaverse/next'
```

## Type

```typescript theme={null}
function useItemInstance(id?: string): WeaverseItemStore | null
```

## Parameters

* `id?: string` — The component instance ID. When omitted, the hook uses the current component ID.

## Returns

* `WeaverseItemStore | null` — The item store, or `null` when the instance cannot be found.

## Common Use Patterns

### Accessing the Current Component

Call the hook without an ID inside a rendered Weaverse component:

```tsx theme={null}
'use client'

import { useItemInstance } from '@weaverse/next'

export function ProductDetails() {
  const item = useItemInstance()

  if (!item) return null

  const { product, selectedVariant, showPricing } = item.data

  return (
    <div className="product-details">
      <h2>{product.title}</h2>
      {showPricing && selectedVariant && (
        <div className="price">${selectedVariant.price.amount}</div>
      )}
    </div>
  )
}
```

### Accessing a Specific Component

```tsx theme={null}
'use client'

import { useItemInstance } from '@weaverse/next'

export function ProductFilterControls() {
  const productGrid = useItemInstance('product-grid-main')

  if (!productGrid) return null

  const { filters, activeFilters } = productGrid.data

  const toggleFilter = (filterId: string) => {
    const nextActiveFilters = activeFilters.includes(filterId)
      ? activeFilters.filter((id: string) => id !== filterId)
      : [...activeFilters, filterId]

    productGrid.setData({ activeFilters: nextActiveFilters })
  }

  return (
    <div className="filter-controls">
      {filters.map((filter) => (
        <button
          key={filter.id}
          onClick={() => toggleFilter(filter.id)}
          className={activeFilters.includes(filter.id) ? 'active' : ''}
        >
          {filter.label}
        </button>
      ))}
    </div>
  )
}
```

### Finding the Closest Weaverse Component

```tsx theme={null}
'use client'

import { useItemInstance } from '@weaverse/next'
import { useEffect, useState, type RefObject } from 'react'

export function useClosestWeaverseItem(
  ref: RefObject<HTMLElement | null>
) {
  const [weaverseId, setWeaverseId] = useState('')
  const weaverseItem = useItemInstance(weaverseId)

  useEffect(() => {
    if (!weaverseItem && ref.current) {
      const closest = ref.current.closest('[data-wv-id]')
      setWeaverseId(closest?.getAttribute('data-wv-id') ?? '')
    }
  }, [ref, weaverseItem])

  return weaverseItem
}
```

## Core Methods and Properties

### `data`

* **Type**: `ElementData`
* **Description**: The serialized component data. It always includes `id` and `type`, plus component-specific fields.

### `setData(update)`

* **Parameters**: `Omit<ElementData, 'id' | 'type'>`
* **Returns**: `ElementData`
* **Description**: Merges the update into the item data and triggers a re-render.

### `triggerUpdate()`

* **Returns**: `void`
* **Description**: Forces the component to re-render without changing its data.

### `_id`

* **Type**: `string`
* **Description**: The component instance ID.

### `_element`

* **Type**: `HTMLElement | null`
* **Description**: The component's DOM node, when available.

## When To Use

* When a component needs its own runtime data or methods
* When you need to interact with a component by instance ID
* When implementing cross-component communication

## Related

* [useParentInstance](/docs/nextjs/api/use-parent-instance) - Access the parent component instance
* [useChildInstances](/docs/nextjs/api/use-child-instances) - Access child component instances
* [useWeaverse](/docs/nextjs/api/use-weaverse) - Access the Weaverse runtime


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.