---
layout: '@/layouts/Doc.astro'
title: ASCII Boxes
---

import Example from '@/components/Example.astro'
import boxStyle from '@webtui/css/utils/box.css?raw'
import badgeStyle from '@webtui/css/components/badge.css?raw'
import buttonStyle from '@webtui/css/components/button.css?raw'

The `box-` utility utilizes CSS `::before` and `::after` pseudo-elements to mimic a boxes drawn with ASCII [Box-drawing characters](https://en.wikipedia.org/wiki/Box-drawing_characters)

<Example
    stylesheets={[boxStyle, badgeStyle, buttonStyle]}
    css={`
        .header {
            display: flex;
            justify-content: space-between;
        }
        #content {
            padding: 0lh 1ch;
            padding-top: 1lh;
            display: flex;
            flex-direction: column;
            gap: 1lh;
        }
        #buttons {
            display: flex;
            justify-content: flex-end;
        }
    `}
    html={`<div box-="square" shear-="both">
    <div class="header">
        <span is-="badge" variant-="background0">top-left</span>
        <span is-="badge" variant-="background0">top-right</span>
    </div>
    <div id="content">
        <p>Lorem ipsum dolor sit amet sit dolor ipsum lorem idk i dont speak french</p>
        <div id="buttons">
            <button box-="round">Cancel</button>
            <button box-="round">Ok</button>
        </div>
    </div>
    <div class="header">
        <span is-="badge" variant-="background0">bottom-left</span>
        <span is-="badge" variant-="background0">bottom-right</span>
    </div>
</div>`}
/>

## Import

```css
@import '@webtui/css/utils/box.css';
```

## Usage

```html
<div box-="square">Hi Mom</div>
```

**Important**: The `box-` utility is **suffixed** with a `-`

Using `box="..."` **will not work**

## Examples

### Border Types

<Example
    stylesheets={[boxStyle]}
    html={`
<div box-="square">Square</div>
<div box-="round">Round</div>
<div box-="double">Double</div>
<div box-="double round">Double + Round</div>
`}
/>

### Shearing

Shearing off top/bottom padding allows overlaying content over the top and/or bottom edges of the box

<Example 
    stylesheets={[
        boxStyle, 
        badgeStyle,
    ]}
    css={`
    .header { 
        display: flex;
        justify-content: space-between; 
}
span {
    background-color: var(--background0);
    padding: 0 1ch;
}`}
    html={`
<!-- Shear off the top edge's padding -->
<div box-="square" shear-="top">
    <div class="header">
        <span>Left</span>
        <span>Right</span>
    </div>
    Caption on Top
</div>

<!-- Shear off the bottom edge's padding -->

<div box-="square" shear-="bottom">
    Caption on Bottom
    <div class="header">
        <span>Left</span>
        <span>Right</span>
    </div>
</div>

<!-- Shear off the padding of both top & bottom edges -->

<div box-="square" shear-="both">
    <div class="header">
        <span>Left</span>
        <span>Right</span>
    </div>
    Caption on Top and Bottom
    <div class="header">
        <span>Left</span>
        <span>Right</span>
    </div>
</div>
`} />

## Reference

### Properties

- `--box-border-color`: The border color of the box
- `--box-rounded-radius`: The border radius of `round` boxes
- `--box-border-width`: The border width for `square` and `round` boxes
- `--box-double-border-width`: The width of boxes with `double` borders

```css
#my-box {
    --box-border-color: cyan;
    --box-rounded-radius: 8px;
    --box-border-width: 1px;
    --box-double-border-width: 1px;
}
```

### Extending

To extend the Box stylesheet, define a CSS rule on the `utils` layer

```css
@layer utils {
    [box-~='square'],
    [box-~='round'],
    [box-~='double'] {
        /* ... */
    }
}
```