Components - Ghostty Config

Overview

The Ghostty Config editor is built with Svelte components organized into setting controls, UI elements, and specialized editors.

Setting Components

These components provide the UI for configuring individual settings.

Color

Location: src/lib/components/settings/Color.svelteA color input component with an interactive color picker popout.

Props

Prop	Type	Default	Description
`value`	`HexColor` (bindable)	-	The current color value
`size`	`number`	`20`	Size of the color display in pixels
`label`	`string`	`""`	Optional label to display on the color
`defaultValue`	`HexColor`	-	Default value for reset functionality

Usage

<Color bind:value={config.background} defaultValue="#000000" size={40} />

Features:

Click to open ColorPicker modal
Right-click to reset to default value
Dynamic border color based on luminosity
Escape key closes the picker

ColorPicker

Location: src/lib/components/ColorPicker.svelteInteractive HSV color picker with hex/RGB display.

Props

Prop	Type	Default	Description
`value`	`HexColor \| ""` (bindable)	-	The current color value
`defaultValue`	`HexColor`	`"#408080"`	Default color when value is empty

Implementation Details

// Color space state management
let {hue, saturation, value: brightness} = $state(rgbToHsv(...hexToRgb(value || defaultValue)));
const [red, green, blue] = $derived.by(() => hsvToRgb(hue, saturation, brightness));

Features:

2D saturation/brightness gradient selector
Horizontal hue slider
Live hex input with validation
RGB value display
Empty state visualization (red X)

Palette

Location: src/lib/components/settings/Palette.svelteGrid display for terminal color palette (256 colors).

Props

Prop	Type	Description
`value`	`HexColor[]` (bindable)	Array of 256 palette colors
`defaultValue`	`HexColor[]`	Default palette for reset

Usage

<Palette bind:value={config.palette} defaultValue={defaults.palette} />

Displays an 8×32 grid where each color shows its index (1-256).

KeybindEditor

Location: src/lib/components/settings/KeybindEditor.svelteAdvanced keybind configuration interface.

Props

Prop	Type	Description
`value`	`string`	The keybind string to edit
`onsave`	`(value: string) => void`	Callback when user saves
`oncancel`	`() => void`	Callback when user cancels

Keybind Structure

type Step = {
  key: string;
  modifiers: string[];  // shift, ctrl, alt, super
};

Features:

Prefix selection (global, all, unconsumed, performable)
Multi-step sequence editor (up to 4 steps)
Action dropdown with argument validation
Special handling for resize_split action
Live preview with error validation
Key name autocomplete from 177+ valid keys

Example Output

ctrl+shift+t=new_tab
global:ctrl+q=quit
ctrl+k>ctrl+v=new_split:down

Dropdown

Location: src/lib/components/settings/Dropdown.svelteSelect dropdown for enum settings.

Props

Prop	Type	Description
`value`	`string` (bindable)	Selected value
`options`	`Array<string \| {name: string, value: string}>`	Options list
`placeholder`	`string`	Optional placeholder text
`change`	`() => void`	Optional change handler

Usage

<Dropdown 
  bind:value={cursorStyle} 
  options={["block", "bar", "underline"]} 
/>

Number

Location: src/lib/components/settings/Number.svelteNumeric input with optional range slider.

Props

Prop	Type	Description
`value`	`number` (bindable)	The numeric value
`min`	`number`	Minimum value
`max`	`number`	Maximum value
`step`	`number`	Step increment
`range`	`boolean`	Show as range slider
`placeholder`	`string`	Placeholder text

Usage

<Number bind:value={fontSize} min={6} max={72} step={1} />
<Number bind:value={opacity} min={0} max={1} step={0.1} range />

Text

Location: src/lib/components/settings/Text.svelteText input for string settings.

Props

Prop	Type	Default	Description
`value`	`string` (bindable)	-	Text value
`placeholder`	`string`	`""`	Placeholder text
`blank`	`boolean`	`false`	Transparent background
`align`	`"left" \| "right"`	`"right"`	Text alignment
`change`	`(e: Event) => void`	-	Change handler

Switch

Location: src/lib/components/settings/Switch.svelteAnimated toggle switch for boolean values.

Props

Prop	Type	Default	Description
`checked`	`boolean` (bindable)	`false`	Switch state
`disabled`	`boolean`	`false`	Disable interaction
`onchange`	`(checked: boolean) => void`	-	Change callback

Styling

Uses CSS custom properties:

--switch-body-color
--switch-checked-color
--switch-active-body-color
--switch-active-checked-color

Checkbox

Location: src/lib/components/settings/Checkbox.svelteCheckbox with animated checkmark.

Props

Prop	Type	Default	Description
`checked`	`boolean` (bindable)	`false`	Checked state
`disabled`	`boolean`	`false`	Disable interaction
`onchange`	`(checked: boolean) => void`	-	Change callback

Features:

SVG checkmark with stroke-dasharray animation
Blue gradient when checked
Grayscale when disabled

Layout Components

Group

Location: src/lib/components/settings/Group.svelteContainer for related settings with optional title.

Props

Prop	Type	Default	Description
`title`	`string`	`""`	Group heading
`note`	`string`	`""`	Subtitle description
`flex`	`string \| number`	`""`	CSS flex value
`borderless`	`boolean`	`false`	Remove background/border
`children`	`Snippet`	-	Content slot

Usage

<Group title="Appearance" note="Visual customization options">
  <Item name="Font Size">
    <Number bind:value={fontSize} />
  </Item>
</Group>

Item

Location: src/lib/components/settings/Item.svelteIndividual setting row with label and control.

Props

Prop	Type	Description
`name`	`string`	Setting label
`note`	`string`	Help text below the control
`children`	`Snippet`	The setting control component

Layout

<div class="setting-item">
  <div class="row">
    <div class="setting-name">{name}</div>
    <div class="setting">{@render children()}</div>
  </div>
  {#if note}<div class="note">{note}</div>{/if}
</div>

Specialized Components

Theme

Location: src/lib/components/settings/Theme.svelteSpecial dropdown that loads color schemes.

Props

Prop	Type	Description
`value`	`string` (bindable)	Theme name
`options`	`Array<string \| {name: string, value: string}>`	Available themes

Implementation

async function change() {
  await setColorScheme(value);
}

When changed, fetches the theme file and updates all color settings (background, foreground, palette, etc.).

UI Components

General-purpose UI components used throughout the application.

Admonition

Location: src/lib/components/Admonition.svelteCallout box for important information or warnings.

Props

Prop	Type	Description
`children`	`Snippet`	Admonition content

Usage

<Admonition>
  This tool will have bugs! Please report them on GitHub.
</Admonition>

Displays content in a highlighted box with visual styling to draw attention.

Tab

Location: src/lib/components/Tab.svelteTab button component for tabbed interfaces.

Props

Prop	Type	Description
`selected`	`boolean`	Whether this tab is active
`onclick`	`() => void`	Click handler
`children`	`Snippet`	Tab label content

Features

Visual active/inactive states
Keyboard accessible
Smooth transitions

Tooltip

Location: src/lib/components/Tooltip.svelteTooltip component with positioning logic.

Props

Prop	Type	Description
`text`	`string`	Tooltip content
`children`	`Snippet`	Element to attach tooltip to

Features

Hover-triggered display
Auto-positioning to avoid viewport edges
Uses tooltip action from src/lib/attachments/tooltip.ts

History

Location: src/lib/components/History.svelteNavigation history controls (back/forward buttons).

Features

Browser-style navigation
Integrates with history store
Disabled state when can’t navigate
Keyboard shortcuts support

Implementation

import {canGoBack, canGoForward, processNavigation} from "$lib/stores/history.svelte";

User

Location: src/lib/components/User.svelteUser profile display component.

Props

Prop	Type	Description
`name`	`string`	User name
`avatar`	`string`	Avatar image URL
`subtext`	`string`	Optional subtitle

Usage

Used on the home page to display the project author information.

Gap

Location: src/lib/components/Gap.svelteSpacer component for layout.

Props

Prop	Type	Default	Description
`size`	`number`	`10`	Gap size in pixels

Usage

<Gap size={20} />

Creates vertical spacing between elements.

Preview Components

These components from src/lib/views/ provide live previews of configuration changes.

CursorPreview

Location: src/lib/views/CursorPreview.svelteAnimated cursor preview showing the current cursor style and color.

Features

Displays animated cursor based on config.cursorStyle
Shows cursor color from config.cursorColor
Supports all cursor styles: block, bar, underline
Includes blinking animation
Displays sample text for context

Usage

Referenced in the Features documentation and visible in the Colors settings panel.

FontPreview

Location: src/lib/views/FontPreview.svelteInteractive font testing playground with sample terminal output.

Features

Live font family preview
Font size adjustment
Bold and italic style toggles
Sample text with code, Unicode, and box-drawing characters
Does not persist changes (for testing only)

Sample Content

$ echo "Testing fonts"
┌─────────────────┐
│ Hello, World! → │
└─────────────────┘

PalettePreview

Location: src/lib/views/PalettePreview.svelteGrid visualization of the 256-color terminal palette.

Features

8×32 color grid layout
Displays all 256 palette colors
Each cell shows its index number
Updates in real-time as palette is modified
Clickable cells to edit individual colors

BaseColorPreview

Location: src/lib/views/BaseColorPreview.sveltePreview component for base terminal colors.

Features

Shows background, foreground, and selection colors
Displays sample selected text
Updates reactively with color changes
Demonstrates actual text rendering

AppIconPreview

Location: src/lib/views/AppIconPreview.sveltemacOS app icon customization preview (macOS-specific feature).

Props

Prop	Type	Description
`config`	`Config`	Configuration object with icon settings

Features

Previews custom app icons with different styles
Shows icon ghost color effects
Displays icon frame styles
macOS-only functionality
Real-time preview of icon appearance

Supported Icon Styles

Default Ghostty icon
Custom icon frames (floating, decorative, etc.)
Ghost color overlays

Page

Location: src/lib/views/Page.svelteLayout wrapper component for all pages.

Props

Prop	Type	Description
`title`	`string`	Page title for browser tab
`children`	`Snippet`	Page content

Features

Sets document title
Provides consistent page layout
Handles navigation integration

Component Patterns

Bindable Props

All setting components use Svelte 5’s $bindable() rune:

let {value = $bindable(), options}: Props = $props();

Derived State

Many components use $derived for reactive computations:

const borderColor = $derived(`rgba(255, 255, 255, ${luminosity(value) * 0.0027451 + 0.3})`);

Snippets

Layout components accept children via snippets:

import type {Snippet} from "svelte";

const {children}: {children: Snippet} = $props();

{@render children()}

Overview

User Guide

Features

Development

Reference

​Overview

​Setting Components

​Props

​Usage

​Props

​Implementation Details

​Props

​Usage

​Props

​Keybind Structure

​Example Output

​Props

​Usage

​Props

​Usage

​Props

​Props

​Styling

​Props

​Layout Components

​Props

​Usage

​Props

​Layout

​Specialized Components

​Props

​Implementation

​UI Components

​Props

​Usage

​Props

​Features

​Props

​Features

​Features

​Implementation

​Props

​Usage

​Props

​Usage

​Preview Components

​Features

​Usage

​Features

​Sample Content

​Features

​Features

​Props

​Features

​Supported Icon Styles

​Props

​Features

​Component Patterns

​Bindable Props

​Derived State

​Snippets

Build docs developers (and LLMs) love

Overview

Setting Components

Props

Usage

Props

Implementation Details

Props

Usage

Props

Keybind Structure

Example Output

Props

Usage

Props

Usage

Props

Props

Styling

Props

Layout Components

Props

Usage

Props

Layout

Specialized Components

Props

Implementation

UI Components

Props

Usage

Props

Features

Props

Features

Features

Implementation

Props

Usage

Props

Usage

Preview Components

Features

Usage

Features

Sample Content

Features

Features

Props

Features

Supported Icon Styles

Props

Features

Component Patterns

Bindable Props

Derived State

Snippets