# useSignal

`useSignal(initialValue, options?)` is render-only and returns one stable
[`WritableSignal`](/reference/types/canvas-runtime/#writablesignal) owned by the current
component hook slot. Its graph edges and writer ownership are released when the
component identity disappears.

See [Use signals and animation](/guides/signals-and-animation/).

Related types: [`WritableSignal`](/reference/types/canvas-runtime/#writablesignal)
and [`SignalOptions`](/reference/types/canvas-runtime/#signaloptions).

## API details from source

<span id="api-useSignal"></span>

Creates one component-owned writable signal identity for a hook slot.

```ts
useSignal: <T>(initialValue: T, options?: SignalOptions<T>) => WritableSignal<T>
```

Related API: [useSignal](/reference/hooks/use-signal/), [SignalOptions](/reference/types/canvas-runtime/#signaloptions), [WritableSignal](/reference/types/canvas-runtime/#writablesignal).

### Parameters

- **`initialValue`** — Value stored when this hook slot is first created.

- **`options`** — Equality comparison and optional diagnostic name. See [SignalOptions](/reference/types/canvas-runtime/#signaloptions).

### Returns

A stable mount-owned writable signal. See [WritableSignal](/reference/types/canvas-runtime/#writablesignal).

### See also

[SignalOptions](/reference/types/canvas-runtime/#signaloptions)

[WritableSignal](/reference/types/canvas-runtime/#writablesignal)

[View source — packages/core/src/lib/hooks/use-signal.ts:15](/source/packages/core/src/lib/hooks/use-signal-ts/#L15)

## Implementation guidance for agents

Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Component-owned state and reactions](/minimal-examples/lifecycle/hooks/): Click to update a signal, derive a value, and publish an imperative effect after commit. [Plain source](/minimal/lifecycle/hooks.tsx)
## Interactive examples

- [Signals and animation](/examples/signals-and-animation/) · [Full page](/experience/signals-and-animation/)
- [Reusable physics panels](/examples/physics-panels/) · [Full page](/experience/physics-panels/)
- [Living Ink](/examples/living-ink/) · [Full page](/experience/living-ink/)
- [Material Lab](/examples/material-lab/) · [Full page](/experience/material-lab/)
- [Growing Reveal](/examples/growing-reveal/) · [Full page](/experience/growing-reveal/)
- [Underwater scene](/examples/underwater/) · [Full page](/experience/underwater/)
- [Energy Transitions](/examples/energy-transitions/) · [Full page](/experience/energy-transitions/)
- [Optional filters](/examples/optional-filters/) · [Full page](/experience/optional-filters/)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.