API Reference

Complete documentation for the <terminal-window> custom element. A vanilla JavaScript web component that simulates a terminal console with customizable commands, themes, cursor styles, and typing effects.

Attributes

Configure the terminal using HTML attributes. All attributes can also be set via JavaScript properties.

Appearance

Attribute	Type	Default	Description
`theme`	string	`"dark"`	Color theme: `"dark"` or `"light"`
`cursor-style`	string	`"block"`	Cursor shape: `"block"`, `"underline"`, or `"bar"`
`cursor-blink`	boolean	`true`	Enable cursor blinking animation
`font-family`	string	`'Consolas', 'Monaco', monospace`	Font family for terminal text
`font-size`	string	`"14px"`	Font size (e.g., "14px", "1rem")
`line-height`	number	`1.4`	Line height multiplier

Header

Attribute	Type	Default	Description
`title`	string	`"Terminal"`	Title displayed in the header bar
`show-header`	boolean	`true`	Show the terminal header bar
`show-controls`	boolean	`true`	Show window control buttons (close, minimize, maximize)
`show-copy`	boolean	`true`	Show the copy button in the header
`show-theme-toggle`	boolean	`true`	Show the theme toggle button

Behavior

Attribute	Type	Default	Description
`prompt`	string	`"$ "`	The command prompt text
`typing-effect`	boolean	`false`	Enable typewriter animation for output
`typing-speed`	number	`30`	Milliseconds per character when typing effect is enabled
`readonly`	boolean	`false`	Disable user input (presentation mode)
`max-lines`	number	`1000`	Maximum number of output lines to keep in buffer
`welcome`	string	—	Welcome message displayed when terminal loads
`enable-vfs`	boolean	`false`	Enable virtual file system with built-in commands (ls, cd, pwd, mkdir, touch, rm, cat)
`persist-history`	boolean	`false`	Persist command history to localStorage across sessions
`force-animations`	boolean	`false`	Force typing animations even when user has prefers-reduced-motion set

Events

Listen for these custom events to respond to terminal activity.

Event	Detail	Description
`command`	`{ command, args, input }`	Fired when a command is executed
`command-result`	`{ command, args, result }`	Fired after a command executes successfully
`command-error`	`{ command, error }`	Fired when a command fails or is not found
`output`	`{ type, content }`	Fired when a line is printed to the terminal
`copy`	`{ text, mode }`	Fired when content is copied to clipboard
`close`	—	Fired when the terminal is closed via the close button
`minimize`	`{ minimized }`	Fired when the terminal is minimized/restored
`fullscreen`	`{ fullscreen }`	Fired when fullscreen mode is toggled
`interrupt`	—	Fired when user presses Ctrl+C

Methods

Control the terminal programmatically using these public methods.

Method	Parameters	Returns	Description
`registerCommand(name, handler)`	`name: string, handler: Function`	`void`	Register a custom command handler
`unregisterCommand(name)`	`name: string`	`void`	Remove a registered command
`registerAlias(alias, command)`	`alias: string, command: string`	`void`	Create an alias for a command
`executeCommand(command)`	`command: string`	`Promise<void>`	Execute a command programmatically
`print(text, type)`	`text: string, type?: string`	`Promise<void>`	Print text to the terminal. Type: "output", "error", "info", "success"
`updateLastLine(text)`	`text: string`	`boolean`	Update the last output line in place. Useful for progress bars and countdowns. Returns true if updated.
`clear()`	—	`void`	Clear all terminal output
`setTheme(theme)`	`theme: 'dark'\|'light'`	`void`	Set the color theme
`toggleTheme()`	—	`void`	Toggle between light and dark theme
`setPrompt(prompt)`	`prompt: string`	`void`	Set the command prompt text
`setCursorStyle(style)`	`style: 'block'\|'underline'\|'bar'`	`void`	Set the cursor style
`setCursorBlink(blink)`	`blink: boolean`	`void`	Enable or disable cursor blinking
`setTypingEffect(enabled, speed)`	`enabled: boolean, speed?: number`	`void`	Enable or disable typing effect. Speed in ms per character.
`skipTypingEffect()`	—	`void`	Skip the current typing animation and show all remaining output immediately
`setForceAnimations(force)`	`force: boolean`	`void`	Force animations to run even when user has prefers-reduced-motion enabled
`hasReducedMotion()`	—	`boolean`	Check if user has prefers-reduced-motion enabled in system settings
`setReadonly(readonly)`	`readonly: boolean`	`void`	Enable or disable readonly mode
`setInputMask(masked)`	`masked: boolean`	`void`	Enable or disable input masking for password prompts
`getHistory()`	—	`string[]`	Get the command history array
`setHistory(history)`	`history: string[]`	`void`	Replace the command history
`clearHistory()`	—	`void`	Clear all command history
`getContent()`	—	`string`	Get all terminal output as plain text
`copyContent(mode)`	`mode: 'all'\|'commands'\|'output'`	`Promise<void>`	Copy terminal content to clipboard
`focus()`	—	`void`	Focus the terminal's input field
`scrollToBottom()`	—	`void`	Scroll to the bottom of the terminal
`close()`	—	`void`	Close the terminal by hiding it
`minimize()`	—	`void`	Toggle the minimized state
`toggleFullscreen()`	—	`void`	Toggle fullscreen mode

registerCommand() Example

// Simple command terminal.registerCommand('hello', () => 'Hello, World!'); // Command with arguments terminal.registerCommand('greet', (args) => `Hello, ${args[0] || 'stranger'}!`); // Async command terminal.registerCommand('fetch-data', async () => { const response = await fetch('/api/data'); return await response.text(); });

registerAlias() Example

terminal.registerAlias('ll', 'ls -la'); terminal.registerAlias('cls', 'clear');

updateLastLine() Example

// Progress bar that updates in place terminal.registerCommand('download', async () => { terminal.print('[ ] 0%'); for (let i = 0; i <= 100; i += 5) { await new Promise(r => setTimeout(r, 100)); const filled = Math.round(i / 5); const bar = '█'.repeat(filled) + ' '.repeat(20 - filled); terminal.updateLastLine(`[${bar}] ${i}%`); } return 'Download complete!'; });

CSS Parts

Style internal elements using the ::part() selector.

Part Name	Description
`terminal`	Main terminal container
`header`	Terminal header bar
`controls`	Window controls container (close, minimize, maximize)
`control-close`	Close button
`control-minimize`	Minimize button
`control-maximize`	Maximize button
`title`	Terminal title text
`actions`	Actions container (theme toggle, copy)
`theme-button`	Theme toggle button
`copy-button`	Copy button
`copy-menu`	Copy dropdown menu
`copy-menu-item`	Copy menu items
`body`	Terminal body (scrollable area)
`output`	Output container
`input-line`	Input line container
`prompt`	Command prompt text
`input-text`	User input text
`cursor`	Cursor element

Styling Example

/* Style the terminal header */ terminal-window::part(header) { background: #2d2d2d; border-bottom: 2px solid #50fa7b; } /* Style the prompt */ terminal-window::part(prompt) { color: #ff79c6; }

Slots

Customize content using named slots.

Slot	Description
`title`	Custom content for the terminal title in the header
`actions`	Custom buttons/actions before the theme and copy buttons
`before-output`	Content inserted before the output area in the terminal body

Slots Example

<terminal-window> <span slot="title">My Custom Terminal</span> <button slot="actions" onclick="runScript()">Run</button> <div slot="before-output"> <p>Welcome to the interactive tutorial!</p> </div> </terminal-window>

CSS Custom Properties

Customize colors and styling using CSS custom properties.

Property	Default (Dark)	Description
`--bg-primary`	`#1a1a2e`	Primary background color
`--bg-secondary`	`#16213e`	Secondary background color
`--bg-header`	`#0f0f23`	Header background color
`--border-color`	`#2a2a4a`	Border color
`--text-primary`	`#e0e0e0`	Primary text color
`--text-secondary`	`#888`	Secondary text color
`--prompt-color`	`#50fa7b`	Prompt color
`--cursor-color`	`#50fa7b`	Cursor color
`--command-color`	`#f8f8f2`	Command text color
`--output-color`	`#e0e0e0`	Output text color
`--error-color`	`#ff5555`	Error text color
`--info-color`	`#8be9fd`	Info text color
`--success-color`	`#50fa7b`	Success text color
`--control-close`	`#ff5f56`	Close button color
`--control-minimize`	`#ffbd2e`	Minimize button color
`--control-maximize`	`#27c93f`	Maximize button color

Built-in Commands

These commands are available by default:

Command	Description
`help`	Display available commands
`clear`	Clear the terminal output
`echo [text]`	Print text to the terminal
`history`	Show command history

VFS Commands

When enable-vfs="true" is set, these additional commands are available:

Command	Description
`ls [path]`	List directory contents
`cd [path]`	Change current directory
`pwd`	Print working directory
`mkdir [name]`	Create a directory
`touch [name]`	Create an empty file
`rm [name]`	Remove a file or directory
`cat [file]`	Display file contents