Skip to content

Latest commit

 

History

History
248 lines (212 loc) · 5.67 KB

3-api-reference.md

File metadata and controls

248 lines (212 loc) · 5.67 KB
Raw

← Back / Next →

3. API Reference

Configuration

The exported object has the following type signature and options:

export type WindowConfig = {
  number: number,
  name: string,
  type: "active" | "normal"
}

export type Theme =
  | "catppuccin-mocha"
  | "catppuccin-latte"
  | "catppuccin-macchiato"
  | "catppuccin-frappe"
  | "nord"
  | "dracula"
  | "onedark"
  | "onelight"
  | "onedark-dark"
  | "onedark-vivid"
  | "tokyonight"
  | "tokyonight-moon"
  | "tokyonight-day"
  | "tokyonight-storm"
  | "ayu"
  | "ayu-dark"
  | "ayu-light"

export type Status = {
  fg?: string,
  bg?: string,
  left?: JSX.Element,
  right?: JSX.Element,
  position?: "top" | "bottom"
}


type Toggle = "on" | "off"

export type Options = {
  terminalOverrides?: string,
  escapeTime?: number,
  paneBaseIndex?: number,
  statusKeys?: "vi" | "emacs",
  modeKeys?: "vi" | "emacs",
  setTitles?: Toggle,
  setTitlesString?: string,
  prefix?: string,
  baseIndex?: number,
  historyLimit?: number,
  defaultTerminal?: string,
  mouse?: string,
  renumberWindows?: Toggle,
  aggressiveResize?: boolean,
}

type TmuxCommand =
  | 'select-pane'
  | 'new-window'
  | 'new-window'
  | 'split-window'
  | 'select-pane'
  | 'select-window'
  | 'kill-pane'
  | 'kill-window'
  | 'resize-pane'
  | 'swap-pane'
  | 'rename-window'
  | 'list-panes'
  | 'list-windows'
  | 'list-sessions'
  | 'attach-session'
  | 'detach-client'
  | 'show-messages'
  | 'display-message'
  | 'copy-mode'
  | 'paste-buffer'

export type Bind = {
  key: string,
  command: TmuxCommand,
  options?: string[]
}

export type BetterTmuxConfig = {
  bindings?: Bind[],
  options?: Options,
  theme?: Theme,
  status?: Status,
  window?: (config: WindowConfig) => JSX.Element
}

Themes

The supported themes are:

  • Catppuccin
  • Nord
  • Dracula

💡 Do you need a theme? Feel free to open a PR; it's pretty simple. Check out this file.

Components

<Box /> and <Text />

These are the most primitive building blocks of BetterTmux. They offer you a way to create your own components within the BetterTmux runtime. They are quite similar in practice; you can use only <Box /> if you want, but I prefer to use <Text /> sometimes to improve semantics and readability.

Example

import { Box, Text } from 'better-tmux'

const MyStatusLeft = () => (
<Box bg='#000000' padding={1}>
 <Text fg='#fafafa'>Testing :)</Text>
</Box>
)

As you notice, since they're components, they can receive props. Here is a complete list of props:

Props Table

Prop Type
bg string
fg string
padding number
paddingLeft number
paddingRight number
gap number
bold boolean
italic boolean

Hooks

useTheme(...)

This hook allows you to get the theme palette based on what you provided to the config object. All the widgets provided by BetterTmux and other defaults are based on this theme.

import { useTheme } from 'better-tmux'

const MyWindow = () => {
  const theme = useTheme()
  return <Box bg={theme.primary}>Window</Box>
}

API Reference

const useTheme: void => ThemePalette;

type ThemePalette = {
  background: string,
  foreground: string,
  primary: string,
  secondary: string,
}

Widgets

Widgets are essentially components that you can import and render to any part of the TMUX status bar.

import { SessionName, Clock } from 'better-tmux/widgets'

const MyStatusLeft = () => <Box>
  <SessionName icon="X" />
  <Clock />
</Box>

<SessionName />

Prop Type
icon string

<Hostname />

Prop Type
icon string

<Calendar />

Prop Type
icon string
format string

<Clock />

import { Clock, tmux } from 'better-tmux/widgets'

const MyStatus = () => <Clock format={`${tmux.globals.month}-${tmux.globals.day}-${tmux.globals.year}`} />
Prop Type
icon string
format string

💡 The format props are used to customize the format and ensure you can format based on your locale.

Utilities

Some nice utilities that enables you access TMUX globals or work with TMUX native features.

tmux

A collection of constants, global variables, etc acessible directly via TypeScript. Example:

import { tmux } from 'better-tmux'

const MyStatusLeft = () => <Box>{tmux.globals.sessionName}</Box>

API Reference

const tmux: {
  globals: {  
    hostname: string,
    sessionName: string,
    hour_24: string,
    hour_12: string,
    hour_24_single: string,
    hour_12_single: string,
    minute: string,
    second: string,
    am_pm_upper: string,
    am_pm_lower: string,
    year: string, 
    month: string, 
    day: string, 
    abbreviated_month: string, 
    full_month: string, 
    abbreviated_day: string, 
    full_day: string, 
    week_number: string, 
    day_of_year: string, 
    day_of_week_number: string,
  }
}

← Back / Next →