goshtoso

module

v0.0.5 Latest Latest Go to latest Published: Jun 6, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/araihu/goshtoso

Links

Open Source Insights

README ¶

Goshtoso

Goshtoso mascot

Goshtoso is a Go UI component library for server-rendered web apps. It combines templ, Tailwind CSS, HTMX, and Alpine.js into a set of importable components with bundled CSS and JavaScript assets.

The project began as a hard fork of PenguinUI and has grown into a Go-first component system for applications that prefer rendered HTML, small client-side sprinkles, and deterministic local assets over CDN-bound copy-paste snippets.

Goshtoso is actively evolving. The components are usable, but the API surface is still being refined as the library moves toward a stable public release.

Highlights

37 templ components for common app UI: forms, navigation, overlays, data display, feedback, layout, and richer inputs.
Server-rendered by default with HTMX-friendly markup and Alpine.js where instant local interaction makes sense.
Bundled assets for Tailwind CSS, Alpine.js, HTMX, htmx extensions, fonts, and images. No runtime CDN dependency is required.
Theme system included with light/dark support and 13 built-in themes.
Two-module repository: a slim publishable library at the repo root and a demo/test site under site/.
Go-native examples and tests using templ generation and Playwright-backed E2E coverage.

Quick Start

Install the library:

go get github.com/araihu/goshtoso@latest

Mount the embedded assets in your server:

package main

import (
    "net/http"

    "github.com/araihu/goshtoso/assets"
)

func main() {
    http.Handle("/assets/", assets.Handler())

    http.ListenAndServe(":8080", nil)
}

Include Goshtoso's CSS and JavaScript in your page shell:

import "github.com/araihu/goshtoso/components/head"

templ Layout() {
    <html>
        <head>
            @head.Dependencies()
        </head>
        <body>
            { children... }
        </body>
    </html>
}

Render components from their packages:

import "github.com/araihu/goshtoso/components/button"

templ Example() {
    @button.Button(button.Config{
        Variant: button.Primary,
        Type:    "button",
    }) {
        Save changes
    }
}

Goshtoso components ship pre-generated, so consumers do not run templ generate on the library itself. You still run templ generate for your own .templ files.

For a complete integration guide, including custom Tailwind builds and manual asset wiring, see docs/USAGE.md.

Component Catalog

All components are imported from:

github.com/araihu/goshtoso/components/<name>

Current components:

accordion        alert       avatar       badge        banner       breadcrumbs
button           card        carousel     chatbubble   checkbox     codeblock
combobox         drawer      dropdown     fileinput    form         head
modal            navbar      pagination   palette      radio        schemafield
select           sidebar     spinner      steps        structuredinput
table            tabs        tagslist     textarea     textinput    toast
toggle           tooltip

Run the demo site to explore variants, API tables, HTMX behavior, Alpine.js states, themes, and example apps:

go run ./site/cmd/server

Then open:

The public documentation site is available at https://goshtoso.araihu.com/.

Using Assets

The recommended path is to serve Goshtoso's embedded assets:

http.Handle("/assets/", assets.Handler())

and let @head.Dependencies() emit the matching stylesheet and script tags. This serves the compiled component CSS, theme tokens, Alpine.js, HTMX, and first-party component scripts from versioned local paths.

If you maintain a custom Tailwind build, Goshtoso also ships a CLI that extracts the compiled CSS or theme source:

go run github.com/araihu/goshtoso/cmd/goshtoso@latest -out=css/goshtoso-base.css

See docs/USAGE.md for the full asset strategy.

Repository Layout

goshtoso/
├── cmd/                     # Thin command entry points
├── components/              # Publishable component library
├── assets/                  # Embedded CSS, JS, fonts, and images
├── css/                     # Tailwind source
├── docs/                    # Consumer and project documentation
├── examples/                # Standalone examples
├── internal/                # Generator internals used by cmd/* tools
└── site/                    # Demo site, example app pages, server, E2E tests

The root module is github.com/araihu/goshtoso. The site/ directory is a separate module for the demo website and test harness.

For local development, create a Go workspace once per clone so the site imports your working-tree copy of the library:

go work init . ./site

Development

Useful commands from the repo root:

# Generate *_templ.go files after editing .templ sources
templ generate
# or
just gp-generate

# Rebuild the embedded Tailwind CSS after editing CSS/theme sources
just css

# Run the demo server on :8090
go run ./site/cmd/server
# or
just gp-dev

# Build the demo server
go build -o bin/server ./site/cmd/server

Run tests:

# Library tests
go test ./...

# Site tests
cd site && go test ./...

# Full Playwright E2E suite
go test ./site/tests/e2e/... -count=1 -timeout 15m

Run lint checks per module:

golangci-lint run
cd site && golangci-lint run

Generated files are part of the repo, but should not be edited by hand:

*_templ.go is generated by templ generate
assets/styles.css is generated by just css

Contributing

See CONTRIBUTING.md for contribution guidelines and CODE_OF_CONDUCT.md for community expectations.

When adding or changing components, keep the component source, demo page, E2E coverage, generated templ output, CSS output, and usage reference in sync.

Credits

Goshtoso began as a hard fork of PenguinUI by Salar Houshvand, transformed from static HTML/Alpine.js examples into an importable Go component library.

License

MIT. See LICENSE.

Directories ¶

Path	Synopsis
assets Package assets provides embedded static files (CSS, JS, images) for Goshtoso components.	Package assets provides embedded static files (CSS, JS, images) for Goshtoso components.
cmd
goshtoso command Command goshtoso extracts embedded Goshtoso assets and reports versions.	Command goshtoso extracts embedded Goshtoso assets and reports versions.
skillgen command
themegen command
vendorgen command
components
accordion templ: version: v0.3.1020	templ: version: v0.3.1020
alert templ: version: v0.3.1020	templ: version: v0.3.1020
avatar templ: version: v0.3.1020	templ: version: v0.3.1020
badge templ: version: v0.3.1020	templ: version: v0.3.1020
banner templ: version: v0.3.1020	templ: version: v0.3.1020
breadcrumbs templ: version: v0.3.1020	templ: version: v0.3.1020
button templ: version: v0.3.1020	templ: version: v0.3.1020
card templ: version: v0.3.1020	templ: version: v0.3.1020
carousel templ: version: v0.3.1020	templ: version: v0.3.1020
chatbubble templ: version: v0.3.1020	templ: version: v0.3.1020
checkbox templ: version: v0.3.1020	templ: version: v0.3.1020
codeblock templ: version: v0.3.1020	templ: version: v0.3.1020
combobox templ: version: v0.3.1020	templ: version: v0.3.1020
drawer templ: version: v0.3.1020	templ: version: v0.3.1020
dropdown templ: version: v0.3.1020	templ: version: v0.3.1020
fileinput templ: version: v0.3.1020	templ: version: v0.3.1020
form templ: version: v0.3.1020	templ: version: v0.3.1020
form/validation
head templ: version: v0.3.1020	templ: version: v0.3.1020
kbd templ: version: v0.3.1020	templ: version: v0.3.1020
link templ: version: v0.3.1020	templ: version: v0.3.1020
modal templ: version: v0.3.1020	templ: version: v0.3.1020
navbar templ: version: v0.3.1020	templ: version: v0.3.1020
pagination templ: version: v0.3.1020	templ: version: v0.3.1020
palette templ: version: v0.3.1020	templ: version: v0.3.1020
radio templ: version: v0.3.1020	templ: version: v0.3.1020
range templ: version: v0.3.1020	templ: version: v0.3.1020
rating templ: version: v0.3.1020	templ: version: v0.3.1020
schemaform templ: version: v0.3.1020	templ: version: v0.3.1020
search templ: version: v0.3.1020	templ: version: v0.3.1020
select templ: version: v0.3.1020	templ: version: v0.3.1020
sidebar templ: version: v0.3.1020	templ: version: v0.3.1020
spinner templ: version: v0.3.1020	templ: version: v0.3.1020
steps templ: version: v0.3.1020	templ: version: v0.3.1020
structuredinput templ: version: v0.3.1020	templ: version: v0.3.1020
table templ: version: v0.3.1020	templ: version: v0.3.1020
tabs templ: version: v0.3.1020	templ: version: v0.3.1020
tagslist templ: version: v0.3.1020	templ: version: v0.3.1020
textarea templ: version: v0.3.1020	templ: version: v0.3.1020
textinput templ: version: v0.3.1020	templ: version: v0.3.1020
toast templ: version: v0.3.1020	templ: version: v0.3.1020
toggle templ: version: v0.3.1020	templ: version: v0.3.1020
tooltip templ: version: v0.3.1020	templ: version: v0.3.1020
internal
skillgen Command skillgen derives the Goshtoso component API reference from source.	Command skillgen derives the Goshtoso component API reference from source.
themegen Command themegen generates assets/goshtoso-theme.css — the self-contained Goshtoso theme source a consumer imports into their own Tailwind v4 build.	Command themegen generates assets/goshtoso-theme.css — the self-contained Goshtoso theme source a consumer imports into their own Tailwind v4 build.
vendorgen Command vendorgen generates assets/vendor_gen.go from the runtime version manifest (assets/js/runtime/versions.json) — the single source of truth for every vendored third-party JS dependency's version, file, and origin.	Command vendorgen generates assets/vendor_gen.go from the runtime version manifest (assets/js/runtime/versions.json) — the single source of truth for every vendored third-party JS dependency's version, file, and origin.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL