How To Use

Learn how to integrate templUI into your projects using the official CLI.

Requirements

Before using templUI, ensure you have these tools installed:

1. Go (1.24 or later)

Check your Go version:

go version

For installation instructions, visit golang.org/dl.

2. templ (v0.3.865 or later)

Install the templ CLI:

go install github.com/a-h/templ/cmd/templ@latest

3. Tailwind CSS Standalone CLI (v4.0.5 or later)

Install the standalone CLI based on your operating system:

Homebrew (macOS):

brew install tailwindcss

macOS (Apple Silicon):

curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-macos-arm64
chmod +x tailwindcss-macos-arm64
sudo mv tailwindcss-macos-arm64 /usr/local/bin/tailwindcss

macOS (Intel):

curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-macos-x64
chmod +x tailwindcss-macos-x64
sudo mv tailwindcss-macos-x64 /usr/local/bin/tailwindcss

Linux (x64):

curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
chmod +x tailwindcss-linux-x64
sudo mv tailwindcss-linux-x64 /usr/local/bin/tailwindcss

Windows (x64):

# On Windows (x64i
# Download from: https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-windows-x64.exe
# Add to your PATH as 'tailwindcss'

Base Configuration

templUI provides pre-configured styles and themes. You will need these files in your project:

1. CSS Configuration file + Base Styles

Create assets/css/input.css with our base styles:

@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));

@theme inline {
  --color-border: var(--border);
  --color-input: var(--input);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(---accent-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-ring: var(--ring);

  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);

  --container-2xl: 1400px;
}

:root {
  --background: hsl(0 0% 100%);
  --foreground: hsl(240 10% 3.9%);
  --muted: hsl(240 4.8% 95.9%);
  --muted-foreground: hsl(240 3.8% 46.1%);
  --popover: hsl(0 0% 100%);
  --popover-foreground: hsl(240 10% 3.9%);
  --card: hsl(0 0% 100%);
  --card-foreground: hsl(240 10% 3.9%);
  --border: hsl(240 5.9% 90%);
  --input: hsl(240 5.9% 90%);
  --primary: hsl(240 5.9% 10%);
  --primary-foreground: hsl(0 0% 98%);
  --secondary: hsl(240 4.8% 95.9%);
  --secondary-foreground: hsl(240 5.9% 10%);
  --accent: hsl(240 4.8% 95.9%);
  --accent-foreground: hsl(240 5.9% 10%);
  --destructive: hsl(0 84.2% 60.2%);
  --destructive-foreground: hsl(0 0% 98%);
  --ring: hsl(240 5.9% 10%);
  --radius: 0.5rem;
}

.dark {
  --background: hsl(240 10% 3.9%);
  --foreground: hsl(0 0% 98%);
  --muted: hsl(240 3.7% 15.9%);
  --muted-foreground: hsl(240 5% 64.9%);
  --popover: hsl(240 10% 3.9%);
  --popover-foreground: hsl(0 0% 98%);
  --card: hsl(240 10% 3.9%);
  --card-foreground: hsl(0 0% 98%);
  --border: hsl(240 3.7% 15.9%);
  --input: hsl(240 3.7% 15.9%);
  --primary: hsl(0 0% 98%);
  --primary-foreground: hsl(240 5.9% 10%);
  --secondary: hsl(240 3.7% 15.9%);
  --secondary-foreground: hsl(0 0% 98%);
  --accent: hsl(240 3.7% 15.9%);
  --accent-foreground: hsl(0 0% 98%);
  --destructive: hsl(0 62.8% 30.6%);
  --destructive-foreground: hsl(0 0% 98%);
  --ring: hsl(240 4.9% 83.9%);
  --radius: 0.5rem;
}

@layer base {
  * {
    @apply border-border;
  }

  body {
    @apply bg-background text-foreground;
    font-feature-settings:
      "rlig" 1,
      "calt" 1;
  }
}

For custom themes and additional styles, check our themes documentation.

Development Tools

Here is our recommended development setup for Go and templ projects, adapted from official documentation and community best practices:

Hot reloading for Go, Templ, and Tailwind
Convenient development commands via Make
Automated file watching and rebuilding

The Makefile configuration is based on the templ documentation and adapted for our use case. While there are many ways to set up your development environment, this configuration provides a solid starting point.

1. Air (Live Reload for Go)

Install Air for automatic Go server rebuilds:

go install github.com/air-verse/air@latest

2. Development Makefile

Create a Makefile in your project root:

# Run templ generation in watch mode
templ:
    templ generate --watch --proxy="http://localhost:8090" --open-browser=false

# Run air for Go hot reload
server:
    air \
    --build.cmd "go build -o tmp/bin/main ./main.go" \
    --build.bin "tmp/bin/main" \
    --build.delay "100" \
    --build.exclude_dir "node_modules" \
    --build.include_ext "go" \
    --build.stop_on_error "false" \
    --misc.clean_on_exit true

# Watch Tailwind CSS changes
tailwind:
    tailwindcss -i ./assets/css/input.css -o ./assets/css/output.css --watch

# Start development server with all watchers
dev:
    make -j3 tailwind templ server

Note about ports:

In this example configuration, the Go application runs on port 8090
templs development server will be available at http://localhost:7331
Adjust the --proxy flag in the templ command if your app uses a different port

3. Start Development Server

Start all development tools with a single command:

make dev

This will:

Watch and compile templ files
Start the Go server with hot reload via Air
Watch and compile Tailwind CSS changes

Or run services individually:

make templ - Watch templ files only
make server - Run Go server only
make tailwind - Watch Tailwind CSS only

Installation (CLI)

The recommended way to use templUI components is via the official CLI tool.

1. Install the templUI CLI

Install the latest version using `go install`:

go install github.com/axzilla/templui/cmd/templui@latest

Verify the installation:

templui -v

2. Initialize templUI in Your Project

Navigate to your projects root directory and run:

templui init

You will be prompted to set directories for components and utils, your Go module name, and a directory for JavaScript files.

You can specify a specific version (tag, branch, commit):

templui init@v0.1.0 # Example: Initialize using version v0.1.0

3. Add Components

Use the `add` command to install specific components and their dependencies into your configured directories.

templui add button card

To install all available components:

templui add *

To install components from a specific version (tag, branch, commit):

templui add@main button # Install button from the main branch

The CLI automatically handles dependencies defined in the manifest and adjusts import paths within the copied `.templ` files to match your projects module path.

📝 JavaScript Components

For components that require JavaScript (like modals, dropdowns, etc.), the CLI automatically:

Downloads the component's JavaScript file
Adds a Script() template to the component

You must include the Script() template in your layout:

@modal.Script()  // Include in your base layout

Each component manages its own JavaScript - no global bundle needed!

4. List Available Components

To see a list of all components and utils available in the manifest (for the default or a specific version):

templui list
templui list@v0.1.0

Copy & Paste

Alternatively, instead of using our CLI, you can copy any component directly from the docs or the GitHub repository and paste it into your project. Just make sure to manually include any required dependencies and adjust import paths accordingly.

Quickstart Template

For a completely new project with everything pre-configured, use our templUI Quickstart template.

Advanced Configuration

For advanced configuration and best practices, refer to the official documentation:

templ - Cache configuration, component patterns, etc.
Tailwind CSS - Custom theming, plugins, optimization