Template functions
Reference for all tinct template functions.
Colour access
get <palette> <role>
Get a colour by role name. Panics if role doesn't exist.
{{ get . "background" | hex }} # #1e1e2e
{{ get . "accent1" | rgb }} # rgb(137, 180, 250)
getSafe <palette> <role>
Safely get a colour. Returns error if role doesn't exist.
{{ $colour, $err := getSafe . "customRole" }}
{{ if $err }}
# Role not found
{{ else }}
colour {{ $colour | hex }}
{{ end }}
has <palette> <role>
Check if a role exists.
{{ if has . "border" }}
border {{ get . "border" | hex }}
{{ else }}
border {{ get . "outline" | hex }}
{{ end }}
getByIndex <palette> <index>
Get colour by index in the AllColors array (sorted by luminance).
{{ $colour, _ := getByIndex . 0 }}
color0 {{ $colour | hex }}
ansi <palette> <colorName>
Find closest palette colour to an ANSI colour name.
Supported names:
- Standard:
black,red,green,yellow,blue,magenta,cyan,white - Bright:
brightblack,brightred,brightgreen,brightyellow,brightblue,brightmagenta,brightcyan,brightwhite - Aliases:
color0-color15,gray,grey,purple, etc. - Extended:
orange,pink,brown,lime,navy,teal,maroon,olive,violet,indigo
color0 {{ ansi . "black" | hex }}
color1 {{ ansi . "red" | hex }}
color2 {{ ansi . "green" | hex }}
ansiSafe <palette> <colorName>
Safely find ANSI colour. Returns error if name not recognized.
{{ $colour, $err := ansiSafe . "customName" }}
Format conversion
All format functions take a ColorValue and return a string.
hex <colour>
Returns #RRGGBB format (no alpha).
{{ get . "background" | hex }}
# Output: #1e1e2e
hexAlpha <colour>
Returns #RRGGBBAA format (with alpha).
{{ get . "scrim" | hexAlpha }}
# Output: #00000052
hexNoHash <colour>
Returns RRGGBB format (no # prefix).
{{ get . "accent1" | hexNoHash }}
# Output: 89b4fa
argb <colour>
Returns #AARRGGBB format (alpha-first, for Qt).
{{ get . "background" | argb }}
# Output: #ff1e1e2e
rgb <colour>
Returns CSS rgb(r,g,b) format.
{{ get . "background" | rgb }}
# Output: rgb(30, 30, 46)
rgba <colour>
Returns CSS rgba(r,g,b,a) format.
{{ get . "scrim" | rgba }}
# Output: rgba(0, 0, 0, 0.32)
rgbDecimal <colour>
Returns r,g,b decimal format (for Hyprland).
{{ get . "accent1" | rgbDecimal }}
# Output: 137,180,250
rgbaDecimal <colour>
Returns r,g,b,a decimal format.
{{ get . "background" | withAlpha 0.93 | rgbaDecimal }}
# Output: 30,30,46,0.93
rgbSpaces <colour>
Returns r g b space-separated format (for Zellij KDL).
{{ get . "accent1" | rgbSpaces }}
# Output: 137 180 250
xterm256 <colour>
Maps the colour to the nearest xterm-256 palette entry and returns it as a
colorN string, for applications that take xterm-256 indices rather than hex
(Midnight Commander, tmux). System colours 0–15 are skipped so the result
doesn't shift with the terminal's own palette.
{{ get . "background" | xterm256 }}
# Output: color235
Alpha manipulation
withAlpha <colour> <alpha>
Returns a new colour with specified alpha (0.0-1.0).
{{ get . "background" | withAlpha 0.85 | rgba }}
# Output: rgba(30, 30, 46, 0.85)
{{ get . "accent1" | withAlpha 0.5 | hexAlpha }}
# Output: #89b4fa80
Metadata
role <colour>
Get the role name of a colour.
{{ $colour := get . "background" }}
{{ role $colour }}
# Output: background
index <colour>
Get the index of a colour in AllColors.
{{ $colour := get . "accent1" }}
{{ index $colour }}
# Output: 4
themeType <palette>
Get theme type ("dark" or "light").
{{ themeType . }}
# Output: dark
count <palette>
Get total number of colours.
{{ count . }}
# Output: 49
Iteration
allRoles <palette>
Get all role names.
{{ range allRoles . }}
# {{ . }}: {{ get $ . | hex }}
{{ end }}
allColors <palette>
Get all colours sorted by luminance.
{{ range $i, $colour := allColors . }}
colour{{ $i }} {{ $colour | hex }}
{{ end }}
String helpers
These take their operands before the subject string, so they chain naturally
in a pipeline. Note this is the reverse of Go's strings.TrimPrefix and
strings.ReplaceAll argument order.
trimPrefix <prefix> <string>
Removes a leading prefix — most often the # on a hex colour, for formats that
want bare hex.
{{ get . "background" | hex | trimPrefix "#" }}
# Output: 1e1e2e
trimSuffix <suffix> <string>
Removes a trailing suffix.
{{ "tinct.conf" | trimSuffix ".conf" }}
# Output: tinct
replace <old> <new> <string>
Replaces every occurrence of old with new. Useful for converting role names
into the identifier style a config format expects.
{{ range $role := allRoles . }}
@define-color {{ $role | replace "_" "-" }} {{ get $ $role | hex }};
{{ end }}
toLower <string> / toUpper <string>
Case conversion.
{{ get . "accent1" | hex | toUpper }}
# Output: #89B4FA
Context fields
Templates receive a ThemeData struct with the following fields:
.WallpaperPath
The canonical path to the source image, suitable for use in configuration files.
Path canonicalization:
| Input type | Output |
|---|---|
Relative path (images/wall.png) | Absolute path (/home/user/images/wall.png) |
Tilde path (~/Pictures/wall.png) | Preserved with tilde (~/Pictures/wall.png) |
URL (https://...) with caching | Local cached path (~/.cache/tinct/images/abc123.jpg) |
| URL without caching | Original URL |
Tilde paths are preserved for portability across machines with different $HOME values.
{{- if .WallpaperPath }}
wallpaper = {{ .WallpaperPath }}
{{- end }}
.WallpaperRawPath
The literal path as provided by the user, before any canonicalization.
This is useful for:
- Displaying the original input to users
- Logging or debugging
- Preserving the exact user intent
{{- if .WallpaperRawPath }}
# Source: {{ .WallpaperRawPath }}
{{- end }}
Examples:
| User input | .WallpaperPath | .WallpaperRawPath |
|---|---|---|
./images/wall.png | /home/user/project/images/wall.png | ./images/wall.png |
~/Pictures/wall.png | ~/Pictures/wall.png | ~/Pictures/wall.png |
https://example.com/img.jpg | ~/.cache/tinct/images/abc123.jpg | https://example.com/img.jpg |
/abs/path/wall.png | /abs/path/wall.png | /abs/path/wall.png |
.ThemeName
The name of the theme (if provided via --theme-name).
{{- if .ThemeName }}
theme {{ .ThemeName }}
{{- end }}