React API Reference

This page provides a comprehensive API reference for Better UI's React hooks, enabling seamless integration of tools into your React components. These hooks provide mechanisms for executing tools, managing their loading and error states, and rendering their results.

Core Types

Before diving into the hooks, let's understand the related types that define their configurations and return values.

UseToolOptions

Configuration options for the useTool and useTools hooks.

• auto: A boolean flag. If true, the tool will automatically execute on component mount and whenever the initialInput (for useTool) or relevant input (for useTools if applied per-tool) changes. Defaults to false.
• context: An optional Partial<ToolContext> object to override or extend the default context passed to the tool's run method. This allows for customization of fetch behavior, cache maps, etc.
• onSuccess: An optional callback function that is invoked when the tool execution completes successfully. It receives the tool's output data as an argument.
• onError: An optional callback function that is invoked if the tool execution encounters an error. It receives the Error object as an argument.

UseToolResult<TInput, TOutput>

The return object provided by the useTool hook, containing the tool's execution state and control functions.

• data: The output data of the tool, typed as TOutput, or null if the tool has not yet executed or failed.
• loading: A boolean indicating whether the tool is currently executing.
• error: An Error object if the last tool execution failed, otherwise null.
• execute: A function to manually trigger the tool's execution. It accepts an optional input object (TInput). If no input is provided, it attempts to use the initialInput supplied to the useTool hook.
• reset: A function to reset the hook's state, clearing data, loading, error, and executed flags.
• executed: A boolean indicating whether the tool has been successfully executed at least once.

Hooks

useTool(tool, initialInput?, options?)

The useTool hook is designed for integrating a single Better UI tool into a React component. It manages the tool's execution, loading states, errors, and provides functions to control its lifecycle.

• tool: The Tool instance to be used.
• initialInput: An optional initial input object (TInput) for the tool. If options.auto is true, the tool will execute with this input on mount and when this input changes.
• options: An optional UseToolOptions object to configure the hook's behavior.
• Returns: A UseToolResult<TInput, TOutput> object.

Example Usage

Manual execution:

Auto execution:

With callbacks:

useTools(tools, options?)

The useTools hook is designed for integrating multiple Better UI tools into a single React component, managing their independent states efficiently. This hook avoids the "hooks-in-loop" anti-pattern by managing all tool states within a single internal state.

• tools: An object where keys are arbitrary names (e.g., 'weather', 'search') and values are Tool instances. It is highly recommended to define this object outside the component or memoize it using React.useMemo to prevent unnecessary re-renders and potential warnings about changing keys.
• options: An optional UseToolOptions object that applies to all tools managed by this hook.
• Returns: An object with the same keys as the tools input, where each value is a UseToolResult object specific to that tool.

Example Usage