Skip to content

Commit 32f497e

Browse files
authored
docs(basic-usage): added global options section
1 parent 5710c72 commit 32f497e

File tree

1 file changed

+34
-1
lines changed

1 file changed

+34
-1
lines changed

docs/2-basic-usage.md

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
[← Back](./1-setup.md) / [Next →](./3-api-reference.md)
22

33
# 2. Basic Usage
4+
- [Understanding customizations](2-basic-usage.md#understanding-customizations)
45
- [Usage of index.tsx](2-basic-usage.md#usage-of-indextsx)
56
- [Integrating with tmux.conf](2-basic-usage.md#integrating-with-your-tmuxconf)
67
- [BetterTmux packages](2-basic-usage.md#bettertmux-packages-better-tmux)
@@ -9,7 +10,7 @@ As we did previously, you used a template to set up your config. This template i
910

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

12-
## Understading the customization
13+
## Understanding customizations
1314
After cloning and setting up your config using our template, you'll end up with something like that in your config:
1415
```typescript
1516
import { BetterTmuxConfig, Box, WindowConfig, useTheme } from 'better-tmux'
@@ -113,6 +114,38 @@ export default {
113114
```
114115
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](https://github.com/bettervim/better-tmux/blob/main/docs/3-api-reference.md#configuration).
115116

117+
### Themes
118+
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.
119+
120+
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.
121+
122+
To ensure your customizations remain consistent with the current theme, use the `useTheme` hook like we did in the example above:
123+
```typescript
124+
const CustomStatusLeft = () => {
125+
const theme = useTheme()
126+
127+
return (
128+
<Box>
129+
<Hostname />
130+
<Box bg={theme.primary} padding={1}>🚀</Box>
131+
<Box bg={theme.background} fg={theme.foreground} padding={1}>Test</Box>
132+
</Box>
133+
134+
)
135+
}
136+
```
137+
138+
### Setting global options
139+
140+
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:
141+
```typescript
142+
export default {
143+
options: { setTitlesString: "title :)" }
144+
}
145+
```
146+
147+
Check out the `options` [API Reference](https://github.com/bettervim/better-tmux/blob/main/docs/3-api-reference.md#configuration) to see more.
148+
116149
## Usage of `index.tsx`
117150

118151
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:

0 commit comments

Comments
 (0)