# WebTUI: a modular CSS library that gives browser pages the look of a terminal

> WebTUI ships terminal-style components as plain CSS, installed from npm and activated through cascade layers. It suits people building TUI-flavoured web pages who want no JavaScript runtime of their own, and it is a poor fit for anyone who needs a widget library with behaviour.

**webtui/webtui** — Modular CSS Library that brings the beauty of Terminal UIs to the browser

- Repository: https://github.com/webtui/webtui
- Website: https://webtui.ironclad.sh
- Stars: 2,444 · Forks: 48
- Language: MDX
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/webtui-webtui

## What WebTUI is for, and who ends up using it

WebTUI styles ordinary HTML so it reads as a terminal interface. The README calls it a "Modular CSS Library that brings the beauty of Terminal UIs to the browser". That sentence is the whole pitch, and it also sets the boundary: this is a styling layer, not an application framework.

The audience follows from that. Someone building a personal site, a documentation page, a dashboard, or a demo that should look like a shell session can drop in the base package and get buttons and boxes that match the aesthetic. The repository topics list astro, css, terminal, theme, ui and ui-library, which matches the shape of the project: a CSS core plus a set of themes.

It is not aimed at teams who want a component library with state, events or accessibility primitives baked in. Nothing in the README promises those, and a CSS-only package cannot supply them. If your requirement is a date picker that manages focus and keyboard navigation, this is the wrong shelf.

## How the cascade layers and attributes actually work

The mechanism is CSS cascade layers plus attribute selectors. The installation guide in the README tells you to declare the layer order first, then import the library:

```css
@layer base, utils, components;

@import '@webtui/css';
```

That single declaration is doing real work. By naming the layers in that order before the import, you fix the precedence between the library's own layers, so a component rule can override a utility rule and both can override base styles without specificity fights. If you import WebTUI without declaring the order, the layers are created in whatever order the imported stylesheet introduces them, which is a decision you have handed to the bundler.

Styling is then applied through attributes rather than class names. The README example uses a bare button, a button with a size- attribute, and a div with a box- attribute:

```html
<button>click</button>
<button size-="large">click me too</button>
<div box-="square">
    <p>content</p>
</div>
```

The trailing hyphen in box- and size- is unusual and worth noticing. These are custom attributes, not standard HTML ones, so they carry no browser behaviour at all. They exist purely as selector hooks, and the values ("square", "large") are whatever the library defines. That keeps your markup free of utility class soup, but it also means the attributes are invisible to tooling that expects classes, and any framework that strips unknown attributes will break the styling silently.

## Installing @webtui/css and getting one box on screen

The README gives four package managers for the base package. Pick whichever your project already uses:

```bash
bun i @webtui/css
npm i @webtui/css
yarn add @webtui/css
pnpm install @webtui/css
```

After that, open your global CSS file and add the layer declaration followed by the import, exactly as shown in the previous section. The order matters: layers first, import second.

With those two steps done, the README's HTML sample should render as terminal-styled controls. A plain button picks up the base look; the one with size-="large" renders larger; the div with box-="square" draws a square-cornered frame around its paragraph. If the buttons look like default browser buttons, the most likely cause is that the import never resolved, since the layer declaration alone produces no visual change.

For anything beyond this, the README points to the installation guide and framework-specific installation pages at webtui.ironclad.sh. It does not reproduce those steps in the repository README, so the site is the place to look for bundler-specific configuration.

## Themes and the Nerd Font plugin are separate packages

WebTUI is a monorepo, and the README lists the officially maintained packages: @webtui/css for the core, @webtui/plugin-nf, and five themes named @webtui/theme-catppuccin, @webtui/theme-gruvbox, @webtui/theme-nord, @webtui/theme-vitesse and @webtui/theme-everforest.

That split is the practical part of the design. You install the core once and add only the theme you want, rather than pulling every palette into your bundle. The plugin-nf package is a separate concern again, and its name suggests Nerd Font glyph support, though the README does not document what it changes on the page or which glyph ranges it covers. Anyone relying on icon glyphs should check the plugin's own documentation before assuming coverage.

Because these are separate npm packages, version drift is possible: the core and a theme can be on different releases. The repository's recent releases are versioned against the project (0.1.8, 0.1.9, 0.1.10) rather than per package, so the release notes are the place to confirm which package versions moved together.

## Where WebTUI stops being the right tool

The clearest limitation is that nothing here has behaviour. A CSS library cannot make a dropdown open, trap focus in a modal, or announce a state change to a screen reader. If your interface needs those, you are pairing WebTUI with something else, and the README does not describe an official companion for that job.

The attribute approach has a second cost. Custom attributes like box- and size- are not part of HTML, so they get no validation, no autocomplete from standard tooling, and no protection from templating layers that drop unrecognised attributes. In a framework that only forwards known props, the styling can vanish without an error.

There is also a build-order dependency. The layer declaration must survive your CSS pipeline intact. A tool that inlines, reorders or scopes imported stylesheets can change the effective order, and the failure mode is subtle: styles still apply, just with the wrong precedence. The README does not document rollback or a troubleshooting path for that case, so teams should confirm the emitted CSS in their own build output before shipping.

## How it compares with a class-based terminal CSS library

The obvious alternative category is a class-based terminal CSS library, such as the one people find when searching for TuiCss. Both aim at the same visual result: browser markup that looks like a text-mode interface.

The difference is in the selector strategy. A class-based library puts the styling hook in the class attribute, which is standard HTML, works with every templating system, and shows up in editor autocomplete. WebTUI instead uses custom attributes with a trailing hyphen and separates concerns through cascade layers, so precedence is declared once at the top of your stylesheet instead of being resolved by specificity per rule.

The trade-off is real in both directions. Class-based libraries integrate with less friction; WebTUI gives you a cleaner override story once the layers are in place, at the cost of non-standard attributes and a build step that has to respect your layer order. If your project already leans on utility classes, the WebTUI approach will feel like a second, parallel system.

## Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-08-12, which is the same date as the 0.1.10 release. Before that, 0.1.9 landed on 2026-06-19 and 0.1.8 on 2026-06-13. Those dates are the only maintenance signal available here; the README does not publish a support policy or a deprecation schedule.

Upgrading is cheap in principle because the package is CSS. There is no runtime to initialise and no API surface to migrate beyond attribute names and layer declarations. In practice, the cost sits in visual regression: a change to a component layer can alter every page that uses it, and a CSS-only project usually has no test that catches that automatically. The release notes are the place to check what changed between 0.1.9 and 0.1.10.

The licence is MIT, which permits commercial and private use and allows modification and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice; if your organisation has specific obligations around attribution, have someone check the LICENSE file in the repository root against your own policy. Note that the themes are separate packages under the same repository, so confirm the licence on each one you install rather than assuming it from the core.

## Conclusion

Adopt WebTUI if you are building a page whose visual language is a terminal and you are comfortable with attribute-driven styling and cascade layers; skip it if you need components that carry behaviour, since the README describes a CSS library and nothing more. Before committing, verify two things in your own build: that your bundler preserves the @layer order you declare, and that the attribute names (box-, size-) do not collide with anything already in your markup. The repository is a Bun and Turborepo monorepo with node >=18 and bun >=1.3.0 in engines, so check that your toolchain can run the same commands the README lists.

## FAQ

### How do I install WebTUI in a project that uses npm?

Run npm i @webtui/css, then in your global CSS file declare the layer order with @layer base, utils, components; and follow it with @import '@webtui/css';. The README lists bun, npm, yarn and pnpm as supported package managers for the same package.

### Does WebTUI require JavaScript to work?

The README describes WebTUI as a modular CSS library and shows installation as a stylesheet import plus HTML attributes, with no JavaScript step. The repository does contain TypeScript and ESLint tooling, but that is build tooling for the monorepo, not a runtime requirement stated for consumers.

### What are the box- and size- attributes in WebTUI?

They are custom attributes used as styling hooks, shown in the README as box-="square" on a div and size-="large" on a button. They are not standard HTML attributes, so they carry no browser behaviour on their own and depend on the WebTUI stylesheet being loaded.

## Sources

- [License: MIT](https://github.com/webtui/webtui/blob/master/LICENSE)
- [Project website](https://webtui.ironclad.sh)
- [README](https://github.com/webtui/webtui/blob/master/README.md)
- [Releases](https://github.com/webtui/webtui/releases)
- [webtui/webtui on GitHub](https://github.com/webtui/webtui)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/webtui-webtui