← Back / Next →

• Understanding customizations
• Usage of index.tsx
• Integrating with tmux.conf
• BetterTmux packages

As we did previously, you used a template to set up your config. This template is essentially a JavaScript/TypeScript project with React pre-configured and better-tmux installed.

From this template, the only thing you need to focus on is the index.tsx; the rest works like any JavaScript project.

After cloning and setting up your config using our template, you'll end up with something like that in your config:

import { BetterTmuxConfig, Box, WindowConfig, useTheme } from 'better-tmux'
import { Clock, Hostname } from 'better-tmux/widgets'

const Window = ({ type, number, name }: WindowConfig) => {
  const theme = useTheme()
  return (
    <Box 
      padding={1} 
      bg={type === 'active' ? theme.primary : theme.background}
      fg={type === 'active' ? theme.background : theme.foreground}
    >
      {number}: {name}
    </Box>
  )
}

const CustomStatusLeft = () => {
  const theme = useTheme()

  return (
    <Box>
      <Hostname />
      <Box bg={theme.primary} padding={1}>🚀</Box>
      <Box bg={theme.background} fg={theme.foreground} padding={1}>Test</Box>
    </Box>

  )
}

export default {
  theme: 'nord',
  options: {
    prefix: 'C-a'
  },
  status: {
    left: <CustomStatusLeft />,
    right: <Clock />,
    position: 'top'
  },
  window: (window) => <Window {...window} />
} satisfies BetterTmuxConfig

Let's break this customizastion into multiple parts to understand what we're doing in here 🏃

As you might know, TMUX allows you to create multiple windows per session. One of the most common customizations is modifying the window appearance, such as setting a layout for the window (e.g., (number): (name)) or changing the colors for each state (active, normal, zoomed, etc.).

With BetterTmux, all you need to customize your windows is to create a component that receives props of type WindowConfig and returns the layout and UI you want. After that, you just need to export this component as a field of the object config window. Here is an example:

const Window = ({ type, number, name }: WindowConfig) => {
  const theme = useTheme()
  return (
    <Box 
      padding={1} 
      bg={type === 'active' ? theme.primary : theme.background}
      fg={type === 'active' ? theme.background : theme.foreground}
    >
      {number}: {name}
    </Box>
  )
}

export default {
  // ... other customizations
  window: (window) => <Window {...window} />
}

💡 You can use the type prop to display different colors or layout based on the type of window, for example: active windows are blue, and normal are red.

TMUX has a status bar with two parts, a status-left and a status-right, with additional configurations related to the status bar itself.

In the above example, we've made some customizations to it, modifying the layout of status-left, status-right, and status-position.

To customize both status-left and status-right, you can create your own component to display pre-built widgets or create your own from scratch using BetterTmux building blocks. After that, you just need to attach them to the config via the status object:

const CustomStatusLeft = () => {
  const theme = useTheme()

  return (
    <Box>
      <Hostname />
      <Box bg={theme.primary} padding={1}>🚀</Box>
      <Box bg={theme.background} fg={theme.foreground} padding={1}>Test</Box>
    </Box>

  )
}
export default {
  status: {
    left: <CustomStatusLeft />,
    position: 'top'
  },
}

Additionally, you can modify other aspects of the status, like bg (background color) or even its position. To see more, check out the API reference of the object config.

As you might have noticed, BetterTmux can handle themes, which is an important part of your configuration. If you've used TMUX for a while, you'll know that changing your TMUX theme often means changing your TMUX layout as well. However, BetterTmux handles theme changes without affecting the UI.

Whether you're switching your status bar using pre-built widgets or building your own, if you want to change the theme to fit your config (like vim or terminal), all you need to do is change the theme field in the configuration.

To ensure your customizations remain consistent with the current theme, use the useTheme hook like we did in the example above:

const CustomStatusLeft = () => {
  const theme = useTheme()

  return (
    <Box>
      <Hostname />
      <Box bg={theme.primary} padding={1}>🚀</Box>
      <Box bg={theme.background} fg={theme.foreground} padding={1}>Test</Box>
    </Box>

  )
}

A common task when creating a tmux.conf is setting global options. This probably makes up 50% of your config, right? BetterTmux offers a way to do that via the options object. For example, if you need to set a title for your session, you would use tmux set -g set-titles-string "title :)". With BetterTmux, you can do it like this:

export default {
  options: { setTitlesString: "title :)" }
}

Check out the options API Reference to see more.

The main configuration file for BetterTmux is index.tsx. This file is where you define your tmux setup using TypeScript and JSX. You'll notice that this file exports an object with your customizations. These configurations are read by the BetterTmux CLI and do the magic for you. To better understand the flow, it's basically like this:

1. Write your customizations using React.
2. Run better-tmux --file /path/to/your-config/index.tsx.
3. And tada 🎉

Notice that the better-tmux CLI reads your object and transforms everything into tmux native configs.

A common and productive approach is to keep your configs together in dotfiles. BetterTmux fits perfectly into this use case if you integrate it with your tmux.conf file. Since tmux.conf is essentially a file read by tmux, all you need to do is add a line to ensure that every reload of your tmux also executes the better-tmux CLI:

# ~/tmux.conf
run-shell 'better-tmux --file /path/to/your-config/index.tsx'

Along with the setup, you'll install the better-tmux package. This package exports some useful resources for your config:

• Building blocks: <Box /> and <Text />
• Pre-built widgets: <Hostname />, <Clock />, <SessionName />, etc.
• TMUX global variables through tmux, such as tmux.globals.sessionName
• Hooks: useTheme()

These resources are used internally by presets and components, but they are available for you to build your own customizations.

Check out the API Reference to see more.

← Back / Next →