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 -v
# 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 configure the destination directories for components and utils, and your projects Go module name.
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.
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