---
description: "Returns the cursor controls of the most recently started createWebAgents (so of WebAgentsProvider), or null."
---

# `currentAgentVisuals`

Returns the cursor controls (`setSpotlight`, `setYieldToUser`) of the most recently started [`createWebAgents`](/docs/reference/core/create-web-agents), so of [`<WebAgentsProvider>`](/docs/reference/react/web-agents-provider), that has a cursor, or `null`. For UI that sits beside the provider without a handle on it: the devtools' Settings switches find the cursor this way, which is why `@webmcp-agents/devtools` needs nothing from `@webmcp-agents/react`.

## Import

```ts
import { currentAgentVisuals } from "@webmcp-agents/core";
```

## Example

A spotlight switch of your own, wired to whatever cursor the page has started.

```ts title="spotlight-switch.ts"
import { currentAgentVisuals } from "@webmcp-agents/core";

// A spotlight switch of your own, beside a provider you have no handle
// on: it drives that provider's cursor, or is disabled without one.
const toggle = document.querySelector<HTMLInputElement>("#spotlight");

if (toggle) {
  toggle.disabled = !currentAgentVisuals();
  toggle.addEventListener("change", () => {
    currentAgentVisuals()?.setSpotlight(toggle.checked);
  });
}
```

## Options

None: `currentAgentVisuals()` takes no arguments.

## Returns

`Pick<AgentVisuals, "setSpotlight" | "setYieldToUser"> | null`: the same object as that instance's `agents.visuals`. `null` when nothing is started, or every started instance has `visuals: false`.

## Notes

- Read it when you need it, not at import time: an instance counts from `start()` to `destroy()`. A React component reads it in an effect: the provider's layout effect has started it by then.
- With several started instances, the latest started wins; one with `visuals: false` is skipped.
- A change made while the cursor is not installed yet (the polyfill still loading) becomes the cursor's starting option.
- On the server it returns `null`: nothing starts there.

## See also

- [`createWebAgents`](/docs/reference/core/create-web-agents), whose `visuals` this returns
- [`installWebAgentsDevtools`](/docs/reference/devtools/install-web-agents-devtools), whose `visuals` defaults to it
- [`installAgentVisuals`](/docs/reference/core/install-agent-visuals), the cursor and its options