How To Use

Learn how to integrate TemplUI into your projects.

Requirements

Before using TemplUI, ensure you have these tools installed:

1. Go (1.20 or later)

Check your Go version:

go version

For installation instructions, visit golang.org/dl.

2. Templ

Install the Templ CLI:

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

3. Tailwind CSS CLI (Standalone)

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 (x64)
# 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. Tailwind Configuration

Create tailwind.config.js:

{/** @type {import('tailwindcss').Config} */
const config = {
  darkMode: ["class"],
  content: ["./**/*.html", "./**/*.templ", "./**/*.go"],
  safelist: ["dark"],
  theme: {
    container: {
      center: true,
      padding: "2rem",
      screens: {
        "2xl": "1400px",
      },
    },
    extend: {
      colors: {
        border: "hsl(var(--border) / <alpha-value>)",
        input: "hsl(var(--input) / <alpha-value>)",
        ring: "hsl(var(--ring) / <alpha-value>)",
        background: "hsl(var(--background) / <alpha-value>)",
        foreground: "hsl(var(--foreground) / <alpha-value>)",
        primary: {
          DEFAULT: "hsl(var(--primary) / <alpha-value>)",
          foreground: "hsl(var(--primary-foreground) / <alpha-value>)",
        },
        secondary: {
          DEFAULT: "hsl(var(--secondary) / <alpha-value>)",
          foreground: "hsl(var(--secondary-foreground) / <alpha-value>)",
        },
        destructive: {
          DEFAULT: "hsl(var(--destructive) / <alpha-value>)",
          foreground: "hsl(var(--destructive-foreground) / <alpha-value>)",
        },
        muted: {
          DEFAULT: "hsl(var(--muted) / <alpha-value>)",
          foreground: "hsl(var(--muted-foreground) / <alpha-value>)",
        },
        accent: {
          DEFAULT: "hsl(var(--accent) / <alpha-value>)",
          foreground: "hsl(var(--accent-foreground) / <alpha-value>)",
        },
        popover: {
          DEFAULT: "hsl(var(--popover) / <alpha-value>)",
          foreground: "hsl(var(--popover-foreground) / <alpha-value>)",
        },
        card: {
          DEFAULT: "hsl(var(--card) / <alpha-value>)",
          foreground: "hsl(var(--card-foreground) / <alpha-value>)",
        },
      },
      borderRadius: {
        lg: "var(--radius)",
        md: "calc(var(--radius) - 2px)",
        sm: "calc(var(--radius) - 4px)",
      },
      fontFamily: {},
    },
  },
};

export default config;

2. CSS Base Styles

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

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 240 10% 3.9%;
    --muted: 240 4.8% 95.9%;
    --muted-foreground: 240 3.8% 46.1%;
    --popover: 0 0% 100%;
    --popover-foreground: 240 10% 3.9%;
    --card: 0 0% 100%;
    --card-foreground: 240 10% 3.9%;
    --border: 240 5.9% 90%;
    --input: 240 5.9% 90%;
    --primary: 346.8 77.2% 49.8%;
    --primary-foreground: 355.7 100% 97.3%;
    --secondary: 240 4.8% 95.9%;
    --secondary-foreground: 240 5.9% 10%;
    --accent: 240 4.8% 95.9%;
    --accent-foreground: 240 5.9% 10%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 0 0% 98%;
    --ring: 346.8 77.2% 49.8%;
    --radius: 0.5rem;
  }
  .dark {
    --background: 20 14.3% 4.1%;
    --foreground: 0 0% 95%;
    --muted: 0 0% 15%;
    --muted-foreground: 240 5% 64.9%;
    --popover: 0 0% 9%;
    --popover-foreground: 0 0% 95%;
    --card: 24 9.8% 10%;
    --card-foreground: 0 0% 95%;
    --border: 240 3.7% 15.9%;
    --input: 240 3.7% 15.9%;
    --primary: 346.8 77.2% 49.8%;
    --primary-foreground: 355.7 100% 97.3%;
    --secondary: 240 3.7% 15.9%;
    --secondary-foreground: 0 0% 98%;
    --accent: 12 6.5% 15.1%;
    --accent-foreground: 0 0% 98%;
    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 0 85.7% 97.3%;
    --ring: 346.8 77.2% 49.8%;
    --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.

3. Alpine.js (CSP-Ready)

TemplUI is CSP-compliant by default using Alpine's CSP build. Use our recommended helper component:

@helpers.AlpineJS()

Or include the CSP-compliant Alpine.js version directly:

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

CSP Compliance in TemplUI

Default: CSP-Ready Components

  • Uses Alpine.js CSP build
  • All components use nonces via templ
  • No inline scripts
  • No external scripts

→ CSP-compliant out of the box!

When Adding External Scripts:

  • Enable CSP middleware
  • Configure allowed domains (HTMX, highlight.js etc.)
  • Add nonce to external script tags

⚠️ Without middleware, external scripts will work but break CSP compliance

4. CSP Middleware

The CSP middleware is only needed when adding external scripts while maintaining CSP compliance:

Example Scenarios:

No Middleware Needed:

  • Using only TemplUI components
  • No external scripts or resources

Middleware Required:

  • When using HTMX
  • When using highlight.js
  • When adding any other external scripts
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 tailwind.config.json content array:

"${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):

  1. Visit our components documentation
  2. Find the component you need
  3. Copy the component code into your project's components folder

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 tailwind.config.json 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.AlpineJS()
@helpers.ComponentScripts()

// Option B: Include Alpine.js and specific component scripts
@helpers.AlpineJS()
@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
@helpers.AlpineJS()
@components.AccordionScript()

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

For a complete list of available components and their usage, visit our components documentation.

Advanced Configuration

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

  • Templ Guide - Cache configuration, component patterns, etc.
  • Tailwind CSS - Custom theming, plugins, optimization
  • Alpine.js - Advanced interactivity, state management

Note: Our quickstart template includes recommended configurations for production use.

Next Steps

Now that you have TemplUI set up, try: