How To Use

Learn how to integrate templUI into your projects.

Requirements

Before using templUI, ensure you have these tools installed:

1. Go (1.23 or later)

Check your Go version:

go version

For installation instructions, visit golang.org/dl.

2. templ (v0.3.833 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'll 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.

2. Alpine.js Installation

Add Alpine.js to your layout template:

Standard Installation (Recommended)

For most projects, use the standard Alpine.js build:

<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Enhanced Security Installation

templUI is built to be CSP-compliant. If your application requires strict Content Security Policy (CSP):

1. Use Alpine.js CSP build instead:

<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/csp@3.x.x/dist/cdn.min.js"></script>

2. Add CSP middleware if you're using external resources (like HTMX, highlight.js):

import "github.com/axzilla/templui/pkg/middleware"

// Optional: Configure CSP for additional external resources
cspConfig := middleware.CSPConfig{
    ScriptSrc: []string{"cdn.jsdelivr.net"}, // Add external script sources here
}

// Apply the middleware to your server
wrappedMux := middleware.WithCSP(cspConfig)(mux)
mux.Handle("GET /", templ.Handler(pages.Landing()))
http.ListenAndServe(":8090", wrappedMux)

Development Tools

Here's 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/cosmtrek/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 templ server tailwind

Note about ports:

In this example configuration, the Go application runs on port 8090
Templ's 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 Options

After installing the requirements, you have three ways to use templUI:

1. Quickstart Template (Recommended for new projects)

For a ready-to-go setup, check out our templUI Quickstart template. It includes all requirements and configurations, using templUI as a package library by default but can be easily modified to use copied components or a mix of both approaches.

2. Package Installation

Install templUI as a Go package:

go get github.com/axzilla/templui

*Required: Additional Tailwind Configuration

When using templUI as a package, add this to your input.css:

@source "${GOPATH}/pkg/mod/github.com/axzilla/templui@*/**/*.{go,templ}";

Replace ${GOPATH} with your actual Go path:

go env GOPATH

3. Copy Components

For maximum customization, copy components directly into your project (requires manual updates).

4. Mix and Match

You can also combine approaches. For example, use some components as a package and copy others for customization. Remember that when using any components as a package (including mix and match), you need to add the GOPATH configuration to your input.css as shown in the Package Installation section.

Using Components

Some components require additional scripts for interactivity. Here's how to set them up:

1. Include Required Scripts

At the top of your layout template, include the necessary scripts:

// Option A: Include Alpine.js and all component scripts (recommended)
@helpers.ComponentScripts()

// Option B: Include Alpine.js and specific component scripts
@components.AccordionScript()
@components.ModalScript()
// ... other specific component scripts as needed

2. Component Types

Static Components (Tailwind CSS only)

Can be used directly without additional script includes:

// Static components (Tailwind only) can be used directly
@components.Button(components.ButtonProps{...})
@components.Card(components.CardProps{...})

Interactive Components (Alpine.js/Vanilla JS)

Require script includes:

// First, include required scripts
@components.AccordionScript()

// Then use the component
@components.Accordion(components.AccordionProps{...})

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
Alpine.js - Advanced interactivity, state management