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 } from '@primereact/headless/terminal';
import { TerminalResponse } from '@primereact/headless/terminal';
 
const { rootProps, promptValueProps, commandResponseProps, state } = useTerminal({ prompt: '$', onCommand: commandHandler });
 
return (
    <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#

Returns spread-ready rootProps, promptValueProps, and commandResponseProps with data attributes and aria-live
Tracks command history in state.commands with text and optional response
Supports synchronous and asynchronous onCommand handlers
Navigates command history with Arrow Up
Clears all commands when onCommand returns null

Behavior#

Command Handler#

The onCommand callback receives the entered text and returns a TerminalResponse — a ReactNode, null to clear, or undefined for no response.

const handler = (text: string): TerminalResponse => {
    if (text === 'clear') return null;
    return `You typed: ${text}`;
};
 
const { state } = useTerminal({ onCommand: handler, elementRef: ref });

Async Commands#

onCommand can return a Promise<TerminalResponse> for asynchronous operations.

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

Command History#

Press Arrow Up to cycle through previously entered commands. The index wraps around to the last command.

const { state } = useTerminal({ prompt: '$', onCommand: handler, elementRef: ref });
 
// state.commands is an array of { text: string, response?: ReactNode }
state.commands.map((cmd) => cmd.text);

Custom Styling with Data Attributes#

The prop objects include data-scope="terminal" and data-part for styling.

[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#

See Terminal Primitive for WAI-ARIA compliance details and keyboard support.