useTerminal

Hook that manages command execution, input state, and command history for a terminal-style interface.

Welcome to PrimeReact Terminal. Type "help" for available commands.

basic-demo

Usage#

import { useTerminal, TerminalResponse } from '@primereact/headless/terminal';

const { rootProps, promptValueProps, commandResponseProps, state } = useTerminal({
    prompt: '$',
    onCommand: commandHandler
});
 
<div {...rootProps}>
    {state.commands.map((cmd, index) => (
        <div key={index}>
            <span>{cmd.text}</span>
            {cmd.response && <div {...commandResponseProps}>{cmd.response}</div>}
        </div>
    ))}
    <input {...promptValueProps} />
</div>;

useTerminal manages command input, execution, and history navigation. See Primitive for a component-based API.

Features#

Command execution — onCommand receives the entered text and returns a ReactNode, a clear signal, or a promise
Command history — state.commands records every entered command alongside its rendered response
History recall — Arrow Up walks backwards through previously entered commands
Async support — onCommand may return Promise<TerminalResponse> for network-backed commands
Live region output — commandResponseProps includes aria-live so responses are announced to assistive tech

Working with callbacks#

Handling commands#

Return a ReactNode to render the response, null to clear the history, or undefined to skip rendering.

const handler = (text: string): TerminalResponse => {
    if (text === 'clear') return null;
    if (text === 'help')
        return (
            <ul>
                <li>clear</li>
                <li>help</li>
            </ul>
        );
    return `Unknown command: ${text}`;
};
 
const terminal = useTerminal({ onCommand: handler });

Async command execution#

Return a promise from onCommand to handle network calls — the response renders once it resolves.

const handler = async (text: string): Promise<TerminalResponse> => {
    const result = await fetch(`/api/cmd?q=${encodeURIComponent(text)}`);
    return result.text();
};

Reading command history#

state.commands is an array of { text, response? } entries — render it directly to show a running log.

const { state } = useTerminal({ onCommand: handler });
 
state.commands.map((cmd) => cmd.text);

Clearing via command#

Return null from onCommand to wipe the terminal, giving users a conventional clear command.

const handler = (text: string): TerminalResponse => {
    if (text === 'clear') return null;
    return `echo: ${text}`;
};

Styling with data attributes#

The prop objects include data-scope="terminal" and a data-part attribute.

Scope	Part
`terminal`	`root`
`terminal`	`promptvalue`
`terminal`	`commandresponse`

[data-scope='terminal'][data-part='root'] {
    background-color: #1e1e1e;
    color: #fff;
    font-family: monospace;
}
 
[data-scope='terminal'][data-part='promptvalue'] {
    background: transparent;
    border: none;
    outline: none;
}
 
[data-scope='terminal'][data-part='commandresponse'] {
    padding-left: 1rem;
}

API#

useTerminal#

Name	Type	Default
`prompt`	`string`	—
Prompt text for each command.
`onCommand`	`TerminalCommandHandler`	—
Callback function invoked when a command is entered. Return value determines the response: - React.ReactNode: Displayed as command response - null: Clears the terminal - undefined: No response shown Supports async functions for delayed responses.

Accessibility#

Enter submits the current command, Up/Down arrows navigate command history, and focus is maintained on the input. See Primitive for full WAI-ARIA compliance details.