Textual CSS Reference
Overview
Complete reference for valid Textual CSS properties, values, and types. Textual CSS differs from web CSS — many web properties are invalid or unsupported.
VALID PROPERTIES
Layout & Sizing
| Property |
Valid Values |
width |
integer, N%, Nw, Nh, Nvw, Nvh, auto, Nfr |
height |
integer, N%, Nw, Nh, Nvw, Nvh, auto, Nfr |
min-width |
integer, percentage, auto |
min-height |
integer, percentage, auto |
max-width |
integer, percentage, auto |
max-height |
integer, percentage, auto |
layout |
grid, horizontal, vertical (NOT flex) |
align |
left|center|right top|middle|bottom |
align-horizontal |
left, center, right |
align-vertical |
top, middle, bottom |
content-align |
left|center|right top|middle|bottom |
dock |
docking position value |
position |
x/y coordinates (ONLY absolute supported) |
offset |
positional offset |
Spacing
| Property |
Valid Values |
margin |
1-4 integers (clockwise: top→right→bottom→left) |
margin-top |
integer |
margin-right |
integer |
margin-bottom |
integer |
margin-left |
integer |
padding |
1-4 integers |
padding-top |
integer |
padding-right |
integer |
padding-bottom |
integer |
padding-left |
integer |
Display & Visibility
| Property |
Valid Values |
display |
block, none (NOT flex, inline, grid for display) |
visibility |
hidden, visible |
Colors & Backgrounds
| Property |
Valid Values |
color |
Named, hex, rgb(), hsl(), hsla() |
background |
<color> with optional <percentage> for opacity |
background-tint |
tint overlay |
tint |
color tint overlay |
text-opacity |
percentage |
opacity |
transparency level |
box-sizing |
border-box, content-box |
Text Styling
| Property |
Valid Values |
text-style |
bold, italic, underline, strike, reverse, none |
text-align |
left, center, right |
text-wrap |
wrap mode values |
text-overflow |
overflow handling |
Borders
| Property |
Valid Values |
border |
<border-style> <color> <percentage> |
border-top |
style/color on top edge only |
border-right |
style/color on right edge only |
border-bottom |
style/color on bottom edge only |
border-left |
style/color on left edge only |
border-title-align |
left, center, right |
border-title-background |
color |
border-title-color |
color |
border-title-style |
text style |
border-subtitle-align |
left, center, right |
border-subtitle-background |
color |
border-subtitle-color |
color |
border-subtitle-style |
text style |
Border Styles: solid, dashed, tall, ascii, blank, double, heavy, hidden, none, hkey, inner, outer, panel, round, thick, vkey, wide
Grid Layout
| Property |
Valid Values |
grid |
grid container |
grid-size |
cols rows |
grid-columns |
<scalar>+ |
grid-rows |
<scalar>+ |
grid-gutter |
<scalar> or <scalar> <scalar> |
column-span |
integer |
row-span |
integer |
Scrollbars
| Property |
Valid Values |
scrollbar-gutter |
gutter handling |
scrollbar-size |
dimensions |
scrollbar-visibility |
visibility mode |
scrollbar-color |
color |
scrollbar-background |
color |
scrollbar-color-hover |
color |
scrollbar-background-hover |
color |
scrollbar-color-active |
color |
scrollbar-background-active |
color |
scrollbar-corner-color |
color |
Links
| Property |
Valid Values |
links |
container |
link-color |
color |
link-background |
color |
link-style |
text style |
link-color-hover |
color |
link-background-hover |
color |
link-style-hover |
text style |
Other
| Property |
Valid Values |
overflow |
auto, scroll, hidden |
overflow-x |
auto, scroll, hidden |
overflow-y |
auto, scroll, hidden |
pointer |
pointer event handling |
layer |
single layer |
layers |
multiple layers |
hatch |
hatch pattern |
keyline |
keyline style |
outline |
outline styling |
INVALID / UNSUPPORTED PROPERTIES
These will cause runtime errors:
position: sticky, position: fixed, position: relativeposition: absolute is only valid position valuetop:, left:, right:, bottom: positioningdisplay: flex — use layout: horizontal/vertical insteaddisplay: grid — use layout: grid insteadgrid-template-columns:, grid-template-rows: — use grid-columns:, grid-rows: insteadmargin: with 3 valuespadding: with 3 valuesmargin: auto, padding: autooverflow: hidden alone (must use overflow-y: hidden)overflow: scroll alone (must specify axes: overflow: scroll auto)
CSS TYPES
<color>
- Named colors:
red, blue, aliceblue, etc.
- Hex:
#RGB, #RRGGBB, #RGBA, #RRGGBBAA
- Functional:
rgb(r,g,b), rgba(r,g,b,a), hsl(h,s%,l%), hsla(h,s%,l%,a)
- CSS variables:
$variable-name
<text-style>
Space-separated: bold, italic, underline, strike, reverse, none
Can combine: bold italic underline
<border>
Style + optional color: heavy red, round orange 50%
<scalar>
- Integer cells:
10
- Fraction:
1fr
- Percent:
50%
- Container-relative:
25w, 75h
- Viewport-relative:
25vw, 75vh
- Auto:
auto
COMMON MISTAKES
| Wrong |
Correct |
display: flex |
layout: horizontal |
display: grid |
layout: grid |
margin: auto |
Remove or use explicit values |
padding: 0 10 20 |
padding: 0 10 20 10 (must be 1, 2, or 4 values) |
position: absolute; top: 0 |
Just dock: top or offset |
overflow: hidden |
overflow-y: hidden |
grid-template-columns: 1fr 2fr |
grid-columns: 1fr 2fr |
VALID DISPLAY VALUES
Only TWO valid values:
block — show widgetnone — hide widget
NOT valid: flex, inline, inline-block, grid
DOCUMENTATION
https://textual.textualize.io/styles/
1---2name: textual-css-reference3description: Use when writing Textual TUI CSS styles or checking valid CSS properties4---56# Textual CSS Reference78## Overview9Complete reference for valid Textual CSS properties, values, and types. Textual CSS differs from web CSS — many web properties are invalid or unsupported.1011## VALID PROPERTIES1213### Layout & Sizing14| Property | Valid Values |15|----------|-------------|16| `width` | integer, `N%`, `Nw`, `Nh`, `Nvw`, `Nvh`, `auto`, `Nfr` |17| `height` | integer, `N%`, `Nw`, `Nh`, `Nvw`, `Nvh`, `auto`, `Nfr` |18| `min-width` | integer, percentage, `auto` |19| `min-height` | integer, percentage, `auto` |20| `max-width` | integer, percentage, `auto` |21| `max-height` | integer, percentage, `auto` |22| `layout` | `grid`, `horizontal`, `vertical` (NOT `flex`) |23| `align` | `left\|center\|right` `top\|middle\|bottom` |24| `align-horizontal` | `left`, `center`, `right` |25| `align-vertical` | `top`, `middle`, `bottom` |26| `content-align` | `left\|center\|right` `top\|middle\|bottom` |27| `dock` | docking position value |28| `position` | x/y coordinates (ONLY `absolute` supported) |29| `offset` | positional offset |3031### Spacing32| Property | Valid Values |33|----------|-------------|34| `margin` | 1-4 integers (clockwise: top→right→bottom→left) |35| `margin-top` | integer |36| `margin-right` | integer |37| `margin-bottom` | integer |38| `margin-left` | integer |39| `padding` | 1-4 integers |40| `padding-top` | integer |41| `padding-right` | integer |42| `padding-bottom` | integer |43| `padding-left` | integer |4445### Display & Visibility46| Property | Valid Values |47|----------|-------------|48| `display` | `block`, `none` (NOT `flex`, `inline`, `grid` for display) |49| `visibility` | `hidden`, `visible` |5051### Colors & Backgrounds52| Property | Valid Values |53|----------|-------------|54| `color` | Named, hex, rgb(), hsl(), hsla() |55| `background` | `<color>` with optional `<percentage>` for opacity |56| `background-tint` | tint overlay |57| `tint` | color tint overlay |58| `text-opacity` | percentage |59| `opacity` | transparency level |60| `box-sizing` | `border-box`, `content-box` |6162### Text Styling63| Property | Valid Values |64|----------|-------------|65| `text-style` | `bold`, `italic`, `underline`, `strike`, `reverse`, `none` |66| `text-align` | `left`, `center`, `right` |67| `text-wrap` | wrap mode values |68| `text-overflow` | overflow handling |6970### Borders71| Property | Valid Values |72|----------|-------------|73| `border` | `<border-style>` `<color>` `<percentage>` |74| `border-top` | style/color on top edge only |75| `border-right` | style/color on right edge only |76| `border-bottom` | style/color on bottom edge only |77| `border-left` | style/color on left edge only |78| `border-title-align` | `left`, `center`, `right` |79| `border-title-background` | color |80| `border-title-color` | color |81| `border-title-style` | text style |82| `border-subtitle-align` | `left`, `center`, `right` |83| `border-subtitle-background` | color |84| `border-subtitle-color` | color |85| `border-subtitle-style` | text style |8687**Border Styles:** `solid`, `dashed`, `tall`, `ascii`, `blank`, `double`, `heavy`, `hidden`, `none`, `hkey`, `inner`, `outer`, `panel`, `round`, `thick`, `vkey`, `wide`8889### Grid Layout90| Property | Valid Values |91|----------|-------------|92| `grid` | grid container |93| `grid-size` | `cols rows` |94| `grid-columns` | `<scalar>+` |95| `grid-rows` | `<scalar>+` |96| `grid-gutter` | `<scalar>` or `<scalar> <scalar>` |97| `column-span` | integer |98| `row-span` | integer |99100### Scrollbars101| Property | Valid Values |102|----------|-------------|103| `scrollbar-gutter` | gutter handling |104| `scrollbar-size` | dimensions |105| `scrollbar-visibility` | visibility mode |106| `scrollbar-color` | color |107| `scrollbar-background` | color |108| `scrollbar-color-hover` | color |109| `scrollbar-background-hover` | color |110| `scrollbar-color-active` | color |111| `scrollbar-background-active` | color |112| `scrollbar-corner-color` | color |113114### Links115| Property | Valid Values |116|----------|-------------|117| `links` | container |118| `link-color` | color |119| `link-background` | color |120| `link-style` | text style |121| `link-color-hover` | color |122| `link-background-hover` | color |123| `link-style-hover` | text style |124125### Other126| Property | Valid Values |127|----------|-------------|128| `overflow` | `auto`, `scroll`, `hidden` |129| `overflow-x` | `auto`, `scroll`, `hidden` |130| `overflow-y` | `auto`, `scroll`, `hidden` |131| `pointer` | pointer event handling |132| `layer` | single layer |133| `layers` | multiple layers |134| `hatch` | hatch pattern |135| `keyline` | keyline style |136| `outline` | outline styling |137138## INVALID / UNSUPPORTED PROPERTIES139140These will cause runtime errors:141- `position: sticky`, `position: fixed`, `position: relative`142- `position: absolute` is only valid position value143- `top:`, `left:`, `right:`, `bottom:` positioning144- `display: flex` — use `layout: horizontal/vertical` instead145- `display: grid` — use `layout: grid` instead146- `grid-template-columns:`, `grid-template-rows:` — use `grid-columns:`, `grid-rows:` instead147- `margin:` with 3 values148- `padding:` with 3 values149- `margin: auto`, `padding: auto`150- `overflow: hidden` alone (must use `overflow-y: hidden`)151- `overflow: scroll` alone (must specify axes: `overflow: scroll auto`)152153## CSS TYPES154155### `<color>`156- Named colors: `red`, `blue`, `aliceblue`, etc.157- Hex: `#RGB`, `#RRGGBB`, `#RGBA`, `#RRGGBBAA`158- Functional: `rgb(r,g,b)`, `rgba(r,g,b,a)`, `hsl(h,s%,l%)`, `hsla(h,s%,l%,a)`159- CSS variables: `$variable-name`160161### `<text-style>`162Space-separated: `bold`, `italic`, `underline`, `strike`, `reverse`, `none`163Can combine: `bold italic underline`164165### `<border>`166Style + optional color: `heavy red`, `round orange 50%`167168### `<scalar>`169- Integer cells: `10`170- Fraction: `1fr`171- Percent: `50%`172- Container-relative: `25w`, `75h`173- Viewport-relative: `25vw`, `75vh`174- Auto: `auto`175176## COMMON MISTAKES177178| Wrong | Correct |179|-------|---------|180| `display: flex` | `layout: horizontal` |181| `display: grid` | `layout: grid` |182| `margin: auto` | Remove or use explicit values |183| `padding: 0 10 20` | `padding: 0 10 20 10` (must be 1, 2, or 4 values) |184| `position: absolute; top: 0` | Just `dock: top` or `offset` |185| `overflow: hidden` | `overflow-y: hidden` |186| `grid-template-columns: 1fr 2fr` | `grid-columns: 1fr 2fr` |187188## VALID DISPLAY VALUES189190Only TWO valid values:191- `block` — show widget192- `none` — hide widget193194NOT valid: `flex`, `inline`, `inline-block`, `grid`195196## DOCUMENTATION197https://textual.textualize.io/styles/
cjthompson