Developing hooks
Built-in hooks are protected members of Component. A custom
hook is therefore a reusable method on a component base class that calls
one or more built-in hooks in a fixed order.
HookedComponent. Static helpers cannot call
the protected hook methods directly.
Create a hook base class
Name custom hooks with a Use prefix. Return the state and
actions the caller needs, and keep every built-in hook call unconditional.
using Donkeh.UILab;
namespace MyApp;
public abstract class HookedComponent : Component
{
protected (bool Value, Action Toggle) UseToggle(bool initial = false)
{
var (value, _, updateValue) = StateWithUpdate(initial);
return (value, () => updateValue(current => !current));
}
}
A component derives from the base class and composes the hooks it needs:
using Donkeh.UILab;
using static Donkeh.UILab._;
namespace MyApp;
public sealed class TogglePanel : HookedComponent
{
public override Node Render()
{
var (open, toggle) = UseToggle();
return H("section", new Props { ClassName = "panel" },
H("button", new Props
{
ClassName = "panel-toggle",
OnClick = toggle
}, Text(open ? "Hide" : "Show")),
Show(open, H("div", new Props { ClassName = "panel-body" },
Text("Panel content"))));
}
}
Compose existing hooks
Custom hooks can call any built-in hook, and can call other custom hooks. The overall order must still be stable across renders.
| Built-in | Use inside a custom hook for |
|---|---|
State | Local values owned by the calling component. |
StateWithUpdate | Updates that depend on the previous value. |
Reducer | Named state transitions or grouped fields. |
Effect | Subscriptions, I/O and cleanup. |
LayoutEffect | Commit-time measurements and adjustments. |
Memo | Derived values that are expensive to build. |
Callback | Stable delegates passed to children. |
UseRef | Mutable values that should not trigger renders. |
UseContext | Reading a typed context inside a reusable hook. |
Typed component base classes
If components share both hooks and props, derive the base class from
Component<TProps>. The public props property remains
available to the derived component.
public abstract class HookedComponent<TProps> : Component<TProps>
where TProps : Props
{
protected bool UseMounted()
{
var (mounted, setMounted) = State(false);
Effect(() => setMounted(true), []);
return mounted;
}
}
Guidelines
- Keep the call order stable. Do not wrap a hook call in an
if, loop, or conditional local function. - Do not call hooks from constructors, lifecycle methods, or event handlers. Hooks belong in
Render. - Return actions, not setters, when possible. A custom hook can hide its state representation behind a small API.
- Keep hooks per component. Two component instances have independent hook slots, even if they use the same base class.
- Use effects for external work. Do not start timers, subscriptions, or blocking work directly in
Render.
Effects inside hooks
A custom hook can own a subscription and return its cleanup. The effect dependencies are evaluated by the renderer; the hook itself does not need to track them.
protected void UseConnection(string endpoint)
{
Effect(() =>
{
var connection = Connect(endpoint);
return () => connection.Dispose();
}, [endpoint]);
}
Keep side effects out of the render body itself. Return a value, or return
an action that the component can attach to an event, and let
Effect own the external lifetime.