Bubberstation/tgui/docs/component-reference.md

# Component Reference

> Notice: This documentation might be out of date, so always check the source
> code to see the most up-to-date information.

<!--
This table of contents must be manually maintained.
Make sure to add new items to this list if you document new components.
-->

- [General Concepts](#general-concepts)
- [`tgui/components`](#tguicomponents)
  - [`AnimatedNumber`](#animatednumber)
  - [`BlockQuote`](#blockquote)
  - [`Box`](#box)
  - [`Button`](#button)
  - [`Button.Checkbox`](#buttoncheckbox)
  - [`Button.Confirm`](#buttonconfirm)
  - [`Button.Input`](#buttoninput)
  - [`ByondUi`](#byondui)
  - [`Collapsible`](#collapsible)
  - [`ColorBox`](#colorbox)
  - [`Dimmer`](#dimmer)
  - [`Divider`](#divider)
  - [`Dropdown`](#dropdown)
  - [`Flex`](#flex)
  - [`Flex.Item`](#flexitem)
  - [`Grid`](#grid)
  - [`Grid.Column`](#gridcolumn)
  - [`Icon`](#icon)
  - [`Icon.Stack`](#iconstack)
  - [`Input`](#input)
  - [`Knob`](#knob)
  - [`LabeledControls`](#labeledcontrols)
  - [`LabeledControls.Item`](#labeledcontrolsitem)
  - [`LabeledList`](#labeledlist)
  - [`LabeledList.Item`](#labeledlistitem)
  - [`LabeledList.Divider`](#labeledlistdivider)
  - [`Modal`](#modal)
  - [`NoticeBox`](#noticebox)
  - [`NumberInput`](#numberinput)
  - [`ProgressBar`](#progressbar)
  - [`RoundGauge`](#roundgauge)
  - [`Section`](#section)
  - [`Slider`](#slider)
  - [`Stack`](#stack)
  - [`Table`](#table)
  - [`Table.Row`](#tablerow)
  - [`Table.Cell`](#tablecell)
  - [`Tabs`](#tabs)
  - [`Tabs.Tab`](#tabstab)
  - [`Tooltip`](#tooltip)
- [`tgui/layouts`](#tguilayouts)
  - [`Window`](#window)
  - [`Window.Content`](#windowcontent)

## General Concepts

These are the components which you can use for interface construction.
If you have trouble finding the exact prop you need on a component,
please note, that most of these components inherit from other basic
components, such as [Box](#box). This component in particular provides a lot
of styling options for all components, e.g. `color` and `opacity`, thus
it is used a lot in this framework.

**Event handlers.**
Event handlers are callbacks that you can attack to various element to
listen for browser events. React supports camelcase (`onClick`) event names.

- Camel case names are what's called _synthetic_ events, and are the
  **preferred way** of handling events in React, for efficiency and
  performance reasons. Please read
  [React Event Handling](https://react.dev/learn/responding-to-events)
  to understand what this is about.

## `tgui/components`

### `AnimatedNumber`

This component provides animations for numeric values.

**Props:**

- `value: number` - Value to animate.
- `initial: number` - Initial value to use in animation when element
  first appears. If you set initial to `0` for example, number will always
  animate starting from `0`, and if omitted, it will not play an initial
  animation.
- `format: value => value` - Output formatter.
  - Example: `value => Math.round(value)`.
- `children: (formattedValue, rawValue) => any` - Pull the animated number to
  animate more complex things deeper in the DOM tree.
  - Example: `(_, value) => <Icon rotation={value} />`

### `BlockQuote`

Just a block quote, just like this example in markdown:

> Here's an example of a block quote.

**Props:**

- See inherited props: [Box](#box)

### `Box`

The Box component serves as a wrapper component for most of the CSS utility
needs. It creates a new DOM element, a `<div>` by default that can be changed
with the `as` property. Let's say you want to use a `<span>` instead:

```jsx
<Box as="span" m={1}>
  <Button />
</Box>
```

This works great when the changes can be isolated to a new DOM element.
For instance, you can change the margin this way.

However, sometimes you have to target the underlying DOM element.
For instance, you want to change the text color of the button. The Button
component defines its own color. CSS inheritance doesn't help.

To workaround this problem, the Box children accept a render props function.
This way, `Button` can pull out the `className` generated by the `Box`.

```jsx
<Box color="primary">{(props) => <Button {...props} />}</Box>
```

**Box Units**

`Box` units, like width, height and margins can be defined in two ways:

- By plain numbers
  - 1 unit equals `1rem` for width, height and positioning properties.
  - 1 unit equals `0.5rem` for margins and paddings.
- By strings with proper CSS units
  - For example: `100px`, `2em`, `1rem`, `100%`, etc.

If you need more precision, you can always use fractional numbers.

Default font size (`1rem`) is equal to `12px`.

**Props:**

- `as: string` - The component used for the root node.
- `color: string` - Applies an atomic `color-<name>` class to the element.
  - See `styles/atomic/color.scss`.
- `width: number` - Box width.
- `minWidth: number` - Box minimum width.
- `maxWidth: number` - Box maximum width.
- `height: number` - Box height.
- `minHeight: number` - Box minimum height.
- `maxHeight: number` - Box maximum height.
- `fontSize: number` - Font size.
- `fontFamily: string` - Font family.
- `lineHeight: number` - Directly affects the height of text lines.
  Useful for adjusting button height.
- `inline: boolean` - Forces the `Box` to appear as an `inline-block`,
  or in other words, makes the `Box` flow with the text instead of taking
  all available horizontal space.
- `m: number` - Margin on all sides.
- `mx: number` - Horizontal margin.
- `my: number` - Vertical margin.
- `mt: number` - Top margin.
- `mb: number` - Bottom margin.
- `ml: number` - Left margin.
- `mr: number` - Right margin.
- `p: number` - Padding on all sides.
- `px: number` - Horizontal padding.
- `py: number` - Vertical padding.
- `pt: number` - Top padding.
- `pb: number` - Bottom padding.
- `pl: number` - Left padding.
- `pr: number` - Right padding.
- `opacity: number` - Opacity, from 0 to 1.
- `bold: boolean` - Make text bold.
- `italic: boolean` - Make text italic.
- `nowrap: boolean` - Stops text from wrapping.
- `preserveWhitespace: boolean` - Preserves line-breaks and spacing in text.
- `textAlign: string` - Align text inside the box.
  - `left` (default)
  - `center`
  - `right`
- `position: string` - A direct mapping to `position` CSS property.
  - `relative` - Relative positioning.
  - `absolute` - Absolute positioning.
  - `fixed` - Fixed positioning.
- `color: string` - An alias to `textColor`.
- `textColor: string` - Sets text color.
  - `#ffffff` - Hex format
  - `rgba(255, 255, 255, 1)` - RGB format
  - `purple` - Applies an atomic `color-<name>` class to the element.
    See `styles/color-map.scss`.
- `backgroundColor: string` - Sets background color.
  - `#ffffff` - Hex format
  - `rgba(255, 255, 255, 1)` - RGB format

### `Button`

Buttons allow users to take actions, and make choices, with a single click.

**Props:**

- See inherited props: [Box](#box)
- `fluid: boolean` - Fill all available horizontal space.
- `icon: string` - Adds an icon to the button.
- `iconPosition?: string` - Set to `'right'` to align the icon to the right of the children
- `color: string` - Button color, as defined in `variables.scss`.
  - There is also a special color `transparent` - makes the button
    transparent and slightly dim when inactive.
- `disabled: boolean` - Disables and greys out the button.
- `selected: boolean` - Activates the button (gives it a green color).
- `tooltip: string` - A fancy, boxy tooltip, which appears when hovering
  over the button.
- `tooltipPosition?: string` - Position of the tooltip. See [`Popper`](#Popper) for valid options.
- `ellipsis: boolean` - If button width is constrained, button text will
  be truncated with an ellipsis. Be careful however, because this prop breaks
  the baseline alignment.
- `title: string` - A native browser tooltip, which appears when hovering
  over the button.
- `children: any` - Content to render inside the button.
- `onClick: function` - Called when element is clicked.
- `verticalAlignContent: string` - Align content vertically using flex. Use lineHeight if the height is static.
  - `top` - align content to the ceiling of the button box.
  - `middle` - align content on the middle of the button box.
  - `bottom` - align content on the ground of the button box.

### `Button.Checkbox`

A ghetto checkbox, made entirely using existing Button API.

**Props:**

- See inherited props: [Button](#button)
- `checked: boolean` - Boolean value, which marks the checkbox as checked.

### `Button.Confirm`

A button with an extra confirmation step, using native button component.

**Props:**

- See inherited props: [Button](#button)
- `confirmContent: string` - Text to display after first click; defaults to "Confirm?"
- `confirmColor: string` - Color to display after first click; defaults to "bad"

### `Button.Input`

A button that turns into an input box after the first click. Turns back into a
button after the user hits enter, defocuses, or hits escape. Enter or blur commits,
while escape cancels.

**Props:**

- See inherited props: [Box](#box)
- `fluid`: fill available horizontal space
- `disabled: boolean` - Disables and greys out the button.
- `onCommit: (value) => void`: sends the value after enter/outside click
- `value: string`: default string to display when the input is shown
- `buttonText: string`: The text to display on the button. Defaults to value if
  none is given.

### `ByondUi`

Displays a BYOND UI element on top of the browser, and leverages browser's
layout engine to position it just like any other HTML element. It is
especially useful if you want to display a secondary game map in your
interface.

Example (button):

```
<ByondUi
  params={{
    id: 'test_button', // optional, can be auto-generated
    parent: 'some_container', // optional, defaults to the current window
    type: 'button',
    text: 'Hello, world!',
  }} />
```

Example (map):

```
<ByondUi
  params={{
    id: 'test_map',
    type: 'map',
  }} />
```

It supports a full set of `Box` properties for layout purposes.

**Props:**

- See inherited props: [Box](#box)
- `params: any` - An object with parameters, which are directly passed to
  the `winset` proc call. You can find a full reference of these parameters
  in [BYOND controls and parameters guide](https://secure.byond.com/docs/ref/skinparams.html).

### `Collapsible`

Displays contents when open, acts as a fluid button when closed. Click to
toggle, closed by default.

**Props:**

- See inherited props: [Box](#box)
- `children: any` - What is collapsed when closed
- `title: string` - Text to display on the button for collapsing
- `color: string` - Color of the button; see [Button](#button)
- `buttons: any` - Buttons or other content to render inline with the button

### `ColorBox`

Displays a 1-character wide colored square. Can be used as a status indicator,
or for visually representing a color.

If you want to set a background color on an element, use a plain
[Box](#box) instead.

**Props:**

- See inherited props: [Box](#box)
- `color: string` - Color of the box.

### `Dimmer`

Dims surrounding area to emphasize content placed inside.

Content is automatically centered inside the dimmer.

**Props:**

- See inherited props: [Box](#box)

### `Divider`

Draws a horizontal or vertical line, dividing a section into groups.
Works like the good old `<hr>` element, but it's fancier.

**Props:**

- `vertical: boolean` - Divide content vertically.
- `hidden: boolean` - Divider can divide content without creating a dividing
  line.

### `Dropdown`

A simple dropdown box component. Lets the user select from a list of options
and displays selected entry.

**Props:**

- See inherited props: [Box](#box)
- See inherited props: [Icon](#icon)
- `options: string[] | DropdownEntry[]` - An array of strings which will be displayed in the
  dropdown when open. See Dropdown.tsx for more advanced usage with DropdownEntry
- `selected: any` - Currently selected entry
- `over: boolean` - Dropdown renders over instead of below
- `color: string` - Color of dropdown button
- `noChevron: boolean` - Whether or not the arrow on the right hand side of the dropdown button is visible
- `displayText: ReactNode` - Text to always display in place of the selected text
- `onClick: (e) => void` - Called when dropdown button is clicked
- `onSelected: (value) => void` - Called when a value is picked from the list, `value` is the value that was picked

### `Flex`

Quickly manage the layout, alignment, and sizing of grid columns, navigation,
components, and more with a full suite of responsive flexbox utilities.

If you are new to or unfamiliar with flexbox, we encourage you to read this
[CSS-Tricks flexbox guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).

Consists of two elements: `<Flex>` and `<Flex.Item>`. Both of them provide
the most straight-forward mapping to flex CSS properties as possible.

One of the most basic usage of flex, is to align certain elements
to the left, and certain elements to the right:

```jsx
<Flex>
  <Flex.Item grow={1}>Button description</Flex.Item>
  <Flex.Item>
    <Button>Perform an action</Button>
  </Flex.Item>
</Flex>
```

Flex item with `grow` property will grow to take all available empty space,
while flex items without grow will take the minimum amount of space. This
effectively places the last flex item to the very end of the flex container.

**Props:**

- See inherited props: [Box](#box)
- ~~`spacing: number`~~ - **Removed in tgui 4.3**,
  use [Stack](#stack) instead.
- `inline: boolean` - Makes flexbox container inline, with similar behavior
  to an `inline` property on a `Box`.
- `direction: string` - This establishes the main-axis, thus defining the
  direction flex items are placed in the flex container.
  - `row` (default) - left to right.
  - `row-reverse` - right to left.
  - `column` - top to bottom.
  - `column-reverse` - bottom to top.
- `wrap: string` - By default, flex items will all try to fit onto one line.
  You can change that and allow the items to wrap as needed with this property.
  - `nowrap` (default) - all flex items will be on one line
  - `wrap` - flex items will wrap onto multiple lines, from top to bottom.
  - `wrap-reverse` - flex items will wrap onto multiple lines from bottom to top.
- `align: string` - Default alignment of all children.
  - `stretch` (default) - stretch to fill the container.
  - `start` - items are placed at the start of the cross axis.
  - `end` - items are placed at the end of the cross axis.
  - `center` - items are centered on the cross axis.
  - `baseline` - items are aligned such as their baselines align.
- `justify: string` - This defines the alignment along the main axis.
  It helps distribute extra free space leftover when either all the flex
  items on a line are inflexible, or are flexible but have reached their
  maximum size. It also exerts some control over the alignment of items
  when they overflow the line.
  - `flex-start` (default) - items are packed toward the start of the
    flex-direction.
  - `flex-end` - items are packed toward the end of the flex-direction.
  - `space-between` - items are evenly distributed in the line; first item is
    on the start line, last item on the end line
  - `space-around` - items are evenly distributed in the line with equal space
    around them. Note that visually the spaces aren't equal, since all the items
    have equal space on both sides. The first item will have one unit of space
    against the container edge, but two units of space between the next item
    because that next item has its own spacing that applies.
  - `space-evenly` - items are distributed so that the spacing between any two
    items (and the space to the edges) is equal.
  - TBD (not all properties are supported in IE11).

### `Flex.Item`

**Props:**

- See inherited props: [Box](#box)
- `order: number` - By default, flex items are laid out in the source order.
  However, the order property controls the order in which they appear in the
  flex container.
- `grow: number | boolean` - This defines the ability for a flex item to grow
  if necessary. It accepts a unitless value that serves as a proportion. It
  dictates what amount of the available space inside the flex container the
  item should take up. This number is unit-less and is relative to other
  siblings.
- `shrink: number | boolean` - This defines the ability for a flex item to
  shrink if necessary. Inverse of `grow`.
- `basis: number | string` - This defines the default size of an element
  before any flex-related calculations are done. Has to be a length
  (e.g. `20%`, `5rem`), an `auto` or `content` keyword.
  - **Important:** IE11 flex is buggy, and auto width/height calculations
    can sometimes end up in a circular dependency. This usually happens, when
    working with tables inside flex (they have wacky internal widths and such).
    Setting basis to `0` breaks the loop and fixes all of the problems.
- `align: string` - This allows the default alignment (or the one specified by
  align-items) to be overridden for individual flex items. See: [Flex](#flex).

### `Grid`

> **Deprecated:** This component is no longer recommended due to the variety
> of bugs that come with table-based layouts.
> We recommend using [Flex](#flex) instead.

Helps you to divide horizontal space into two or more equal sections.
It is essentially a single-row `Table`, but with some extra features.

Example:

```jsx
<Grid>
  <Grid.Column>
    <Section title="Section 1">Hello world!</Section>
  </Grid.Column>
  <Grid.Column size={2}>
    <Section title="Section 2">Hello world!</Section>
  </Grid.Column>
</Grid>
```

**Props:**

- See inherited props: [Table](#table)

### `Grid.Column`

**Props:**

- See inherited props: [Table.Cell](#tablecell)
- `size: number` (default: 1) - Size of the column relative to other columns.

### `Icon`

Renders one of the FontAwesome icons of your choice.

```jsx
<Icon name="plus" />
```

To smoothen the transition from v4 to v5, we have added a v4 semantic to
transform names with `-o` suffixes to FA Regular icons. For example:

- `square` will get transformed to `fas square`
- `square-o` will get transformed to `far square`

**Props:**

- See inherited props: [Box](#box)
- `name: string` - Icon name.
- `size: number` - Icon size. `1` is normal size, `2` is two times bigger.
  Fractional numbers are supported.
- `rotation: number` - Icon rotation, in degrees.
- `spin: boolean` - Whether an icon should be spinning. Good for load
  indicators.

### `Icon.Stack`

Renders children icons on top of each other in order to make your own icon.

```jsx
<Icon.Stack>
  <Icon name="pen" />
  <Icon name="slash" />
</Icon.Stack>
```

**Props:**

- See inherited props: [Box](#box)
- `children: Icon` - Icons to stack.

### `Input`

A basic text input, which allow users to enter text into a UI.

> Input does not support custom font size and height due to the way
> it's implemented in CSS. Eventually, this needs to be fixed.

**Props:**

- See inherited props: [Box](#box)
- `value: string` - The initial value displayed on the input.
- `placeholder: string` - Text placed into Input box when it's empty,
  otherwise nothing. Clears automatically when focused.
- `fluid: boolean` - Fill all available horizontal space.
- `selfClear: boolean` - Clear after hitting enter, as well as remain focused
  when this happens. Useful for things like chat inputs.
- `onChange: (e, value) => void` - Fires when the user clicks out or presses enter.
- `onEnter: (e, value) => void` - Fires when the user hits enter.
- `onEscape: (e) => void` - Fires when the user hits escape.
- `onInput: (e, value) => void` - Fires when the user types into the input.
- `expensive: boolean` - Introduces a delay before updating the input. Useful for large filters,
  where you don't want to update on every keystroke.

### `Knob`

A radial control, which allows dialing in precise values by dragging it
up and down.

Single click opens an input box to manually type in a number.

**Props:**

- See inherited props: [Box](#box)
- `animated: boolean` - Animates the value if it was changed externally.
- `bipolar: boolean` - Knob can be bipolar or unipolar.
- `size: number` - Relative size of the knob. `1` is normal size, `2` is two
  times bigger. Fractional numbers are supported.
- `color: string` - Color of the outer ring around the knob.
- `value: number` - Value itself, controls the position of the cursor.
- `unit: string` - Unit to display to the right of value.
- `minValue: number` - Lowest possible value.
- `maxValue: number` - Highest possible value.
- `fillValue: number` - If set, this value will be used to set the fill
  percentage of the outer ring independently of the main value.
- `ranges: { color: [from, to] }` - Applies a `color` to the outer ring around
  the knob based on whether the value lands in the range between `from` and `to`.
  See an example of this prop in [ProgressBar](#progressbar).
- `step: number` (default: 1) - Adjust value by this amount when
  dragging the input.
- `stepPixelSize: number` (default: 1) - Screen distance mouse needs
  to travel to adjust value by one `step`.
- `format: value => value` - Format value using this function before
  displaying it.
- `suppressFlicker: number` - A number in milliseconds, for which the input
  will hold off from updating while events propagate through the backend.
  Default is about 250ms, increase it if you still see flickering.
- `onChange: (e, value) => void` - An event, which fires when you release
  the input, or successfully enter a number.
- `onDrag: (e, value) => void` - An event, which fires about every 500ms
  when you drag the input up and down, on release and on manual editing.

### `LabeledControls`

LabeledControls is a horizontal grid, that is designed to hold various
controls, like [Knobs](#knob) or small [Buttons](#button). Every item in
this grid is labeled at the bottom.

**Props:**

- See inherited props: [Box](#box)
- `children: LabeledControls.Item` - Items to render.

### `LabeledControls.Item`

**Props:**

- See inherited props: [Box](#box)
- `label: string` - Item label.

### `LabeledList`

LabeledList is a continuous, vertical list of text and other content, where
every item is labeled. It works just like a two column table, where first
column is labels, and second column is content.

```jsx
<LabeledList>
  <LabeledList.Item label="Item">Content</LabeledList.Item>
</LabeledList>
```

If you want to have a button on the right side of an item (for example,
to perform some sort of action), there is a way to do that:

```jsx
<LabeledList>
  <LabeledList.Item label="Item" buttons={<Button>Click me!</Button>}>
    Content
  </LabeledList.Item>
</LabeledList>
```

**Props:**

- `children: LabeledList.Item` - Items to render.

### `LabeledList.Item`

**Props:**

- `className: string` - Applies a CSS class to the element.
- `label: string|ReactNode` - Item label.
- `labelWrap: boolean` - Lets the label wrap and makes it not take the minimum width.
- `labelColor: string` - Sets the color of the label.
- `color: string` - Sets the color of the content text.
- `textAlign: string` - Align the content text.
  - `left` (default)
  - `center`
  - `right`
- `verticalAlign: string` - Align both the label and the content vertically.
  - `baseline` (default)
  - `top`
  - `middle`
  - `bottom`
- `buttons: any` - Buttons to render aside the content.
- `children: any` - Content of this labeled item.

### `LabeledList.Divider`

Adds some empty space between LabeledList items.

Example:

```jsx
<LabeledList>
  <LabeledList.Item label="Foo">Content</LabeledList.Item>
  <LabeledList.Divider size={1} />
</LabeledList>
```

**Props:**

- `size: number` - Size of the divider.

### `Modal`

A modal window. Uses a [Dimmer](#dimmer) under the hood, and dynamically
adjusts its own size to fit the content you're trying to display.

Must be a direct child of a layout component (e.g. [Window](#window)).

**Props:**

- See inherited props: [Box](#box)

### `NoticeBox`

A notice box, which warns you about something very important.

**Props:**

- See inherited props: [Box](#box)
- `info: boolean` - Info box
- `success: boolean` - Success box
- `warning: bolean` - Warning box
- `danger: boolean` - Danger box

### `NumberInput`

A fancy, interactive number input, which you can either drag up and down
to fine tune the value, or single click it to manually type a number.

**Props:**

- `animated: boolean` - Animates the value if it was changed externally.
- `disabled: boolean` - Makes the input field uneditable & non draggable to prevent user changes
- `fluid: boolean` - Fill all available horizontal space.
- `value: string|number` - Value itself.
- `unit: string` - Unit to display to the right of value.
- `minValue: number` - Lowest possible value.
- `maxValue: number` - Highest possible value.
- `step: number` - Adjust value by this amount when
  dragging the input.
- `stepPixelSize: number` (default: 1) - Screen distance mouse needs
  to travel to adjust value by one `step`.
- `width: string` - Width of the element, in `Box` units or pixels.
- `height: string` - Height of the element, in `Box` units or pixels.
- `lineHeight: string` - lineHeight of the element, in `Box` units or pixels.
- `fontSize: string` - fontSize of the element, in `Box` units or pixels.
- `format: (value: number) => string` - Format value using this function before
  displaying it.
- `onChange: (value: number) => void` - An event, which fires when you release
  the input, or successfully enter a number.
- `onDrag: (value: number) => void` - An event, which fires about every 500ms
  when you drag the input up and down, on release and on manual editing.

### `Popper`

Popper lets you position elements so that they don't go out of the bounds of the window. See [popper.js](https://popper.js.org/) for more information.

**Props:**

- `content: ReactNode` - The content that will be put inside the popper.
- `isOpen: boolean` - Whether or not the popper is open.
- `onClickOutside?: (e) => void` - A function that will be called when the user clicks outside of the popper.
- `placement?: string` - The placement of the popper. See [https://popper.js.org/docs/v2/constructors/#placement]

### `ProgressBar`

Progress indicators inform users about the status of ongoing processes.

```jsx
<ProgressBar value={0.6} />
```

Usage of `ranges` prop:

```jsx
<ProgressBar
  ranges={{
    good: [0.5, Infinity],
    average: [0.25, 0.5],
    bad: [-Infinity, 0.25],
  }}
  value={0.6}
/>
```

**Props:**

- `value: number` - Current progress as a floating point number between
  `minValue` (default: 0) and `maxValue` (default: 1). Determines the
  percentage and how filled the bar is.
- `minValue: number` - Lowest possible value.
- `maxValue: number` - Highest possible value.
- `ranges: { color: [from, to] }` - Applies a `color` to the progress bar
  based on whether the value lands in the range between `from` and `to`.
- `color: string` - Color of the progress bar. Can take any of the following formats:
  - `#ffffff` - Hex format
  - `rgb(r,g,b) / rgba(r,g,b,a)` - RGB format
  - `<name>` - the name of a `color-<name>` CSS class. See `CSS_COLORS` in `constants.js`.
  - `<name>` - the name of a base CSS color, if not overridden by the definitions above.
- `children: any` - Content to render inside the progress bar.

### `RoundGauge`

The RoundGauge component provides a visual representation of a single metric, as well as being capable of showing informational or cautionary boundaries related to that metric.

```jsx
<RoundGauge
  size={1.75}
  value={tankPressure}
  minValue={0}
  maxValue={pressureLimit}
  alertAfter={pressureLimit * 0.7}
  ranges={{
    good: [0, pressureLimit * 0.7],
    average: [pressureLimit * 0.7, pressureLimit * 0.85],
    bad: [pressureLimit * 0.85, pressureLimit],
  }}
  format={formatPressure}
/>
```

The alert on the gauge is optional, and will only be shown if the `alertAfter` prop is defined. When defined, the alert will begin to flash the respective color upon which the needle currently rests, as defined in the `ranges` prop.

**Props:**

- See inherited props: [Box](#box)
- `value: number` - The current value of the metric.
- `minValue: number` (default: 0) - The lower bound of the guage.
- `maxValue: number` (default: 1) - The upper bound of the guage.
- `ranges: { color: [from, to] }` (default: `{ "good": [0, 1] }`) - Provide regions of the guage to color between two specified values of the metric.
- `alertAfter: number` (optional) - When provided, will cause an alert symbol on the gauge to begin flashing in the color upon which the needle currently rests, as defined in `ranges`.
- `alertBefore: number` (optional) - As with alertAfter, but alerts below a value. If both are set, and alertAfter comes earlier, the alert will only flash when the needle is between both values. Otherwise, the alert will flash when on the active side of either threshold.
- `format: function(value) => string` (optional) - When provided, will be used to format the value of the metric for display.
- `size: number` (default: 1) - When provided scales the gauge.

### `Section`

Section is a surface that displays content and actions on a single topic.

They should be easy to scan for relevant and actionable information.
Elements, like text and images, should be placed in them in a way that
clearly indicates hierarchy.

Section can also be titled to clearly define its purpose.

```jsx
<Section title="Cargo">Here you can order supply crates.</Section>
```

If you want to have a button on the right side of an section title
(for example, to perform some sort of action), there is a way to do that:

```jsx
<Section title="Cargo" buttons={<Button>Send shuttle</Button>}>
  Here you can order supply crates.
</Section>
```

**New:** Sections can now be nested, and will automatically font size of the
header according to their nesting level. Previously this was done via `level`
prop, but now it is automatically calculated.

- See inherited props: [Box](#box)
- `title: string` - Title of the section.
- `buttons: any` - Buttons to render aside the section title.
- `fill: boolean` - If true, fills all available vertical space.
- `fitted: boolean` - If true, removes all section padding.
- `scrollable: boolean` - Shows or hides the scrollbar.
- `children: any` - Content of this section.

### `Slider`

A horizontal, [ProgressBar](#progressbar)-like control, which allows dialing
in precise values by dragging it left and right.

Single click opens an input box to manually type in a number.

**Props:**

- See inherited props: [Box](#box)
- `animated: boolean` - Animates the value if it was changed externally.
- `color: string` - Color of the slider.
- `value: number` - Value itself, controls the position of the cursor.
- `unit: string` - Unit to display to the right of value.
- `minValue: number` - Lowest possible value.
- `maxValue: number` - Highest possible value.
- `fillValue: number` - If set, this value will be used to set the fill
  percentage of the progress bar filler independently of the main value.
- `ranges: { color: [from, to] }` - Applies a `color` to the slider
  based on whether the value lands in the range between `from` and `to`.
  See an example of this prop in [ProgressBar](#progressbar).
- `step: number` (default: 1) - Adjust value by this amount when
  dragging the input.
- `stepPixelSize: number` (default: 1) - Screen distance mouse needs
  to travel to adjust value by one `step`.
- `format: value => value` - Format value using this function before
  displaying it.
- `suppressFlicker: number` - A number in milliseconds, for which the input
  will hold off from updating while events propagate through the backend.
  Default is about 250ms, increase it if you still see flickering.
- `onChange: (e, value) => void` - An event, which fires when you release
  the input, or successfully enter a number.
- `onDrag: (e, value) => void` - An event, which fires about every 500ms
  when you drag the input up and down, on release and on manual editing.

### `Stack`

A higher-level component, that is based on [Flex](#flex). The main difference
from `Flex`, is that this component automatically adds spacing between
all stack items, reducing the boilerplate that you have to write!

Consists of two elements: `<Stack>` and `<Stack.Item>`.

Stacks can be vertical by adding a `vertical` property.

**Example:**

```jsx
<Stack>
  <Stack.Item grow>Button description</Stack.Item>
  <Stack.Item>
    <Button>Perform an action</Button>
  </Stack.Item>
</Stack>
```

**Example of a high-level window layout:**

Stacks can be used for high level window layout.
Make sure to use the `fill` property.

```jsx
<Window>
  <Window.Content>
    <Stack fill>
      <Stack.Item>
        <Section fill>Sidebar</Section>
      </Stack.Item>
      <Stack.Item grow>
        <Stack fill vertical>
          <Stack.Item grow>
            <Section fill scrollable>
              Main content
            </Section>
          </Stack.Item>
          <Stack.Item>
            <Section>Bottom pane</Section>
          </Stack.Item>
        </Stack>
      </Stack.Item>
    </Stack>
  </Window.Content>
</Window>
```

**Props:**

- See inherited props: [Flex](#flex)
- `fill: boolean` - If set, stack will fill all available height.
- `vertical: boolean` - If set, stack will work in vertical mode.

### `Stack.Item`

**Props:**

- See inherited props: [Flex.Item](#flexitem)

### `Table`

A straight forward mapping to a standard html table, which is slightly
simplified (does not need a `<tbody>` tag) and with sane default styles
(e.g. table width is 100% by default).

Example:

```jsx
<Table>
  <Table.Row>
    <Table.Cell bold>Hello world!</Table.Cell>
    <Table.Cell collapsing color="label">
      Label
    </Table.Cell>
  </Table.Row>
</Table>
```

**Props:**

- See inherited props: [Box](#box)
- `collapsing: boolean` - Collapses table to the smallest possible size.

### `Table.Row`

A straight forward mapping to `<tr>` element.

**Props:**

- See inherited props: [Box](#box)

### `Table.Cell`

A straight forward mapping to `<td>` element.

**Props:**

- See inherited props: [Box](#box)
- `collapsing: boolean` - Collapses table cell to the smallest possible size,
  and stops any text inside from wrapping.

### `Tabs`

Tabs make it easy to explore and switch between different views.

Here is an example of how you would construct a simple tabbed view:

```jsx
<Tabs>
  <Tabs.Tab
    selected={tabIndex === 1}
    onClick={() => setTabIndex(1)}>
    Tab one
  </Tabs.Tab>
  <Tabs.Tab
    selected={tabIndex === 2}
    onClick={() => setTabIndex(2)}>
    Tab two
  </Tabs.Tab>
</Tabs>
<Box>
  Tab selected: {tabIndex}
</Box>
```

Notice that tabs do not contain state. It is your job to track the selected
tab, handle clicks and place tab content where you need it. In return, you get
a lot of flexibility in regards to how you can layout your tabs.

Tabs also support a vertical configuration. This is usually paired with
[Stack](#stack) to render tab content to the right.

```jsx
<Stack>
  <Stack.Item>
    <Tabs vertical>...</Tabs>
  </Stack.Item>
  <Stack.Item grow={1} basis={0}>
    Tab content.
  </Stack.Item>
</Stack>
```

If you need to combine a tab section with other elements, or if you want to
add scrollable functionality to tabs, pair them with the [Section](#section)
component:

```jsx
<Section fill fitted scrollable width="128px">
  <Tabs vertical>...</Tabs>
  ... other things ...
</Section>
```

**Props:**

- See inherited props: [Box](#box)
- `fluid: boolean` - If true, tabs will take all available horizontal space.
- `fill: boolean` - Similarly to `fill` on [Section](#section), tabs will fill
  all available vertical space. Only makes sense in a vertical configuration.
- `vertical: boolean` - Use a vertical configuration, where tabs will be
  stacked vertically.
- `children: Tab[]` - This component only accepts tabs as its children.

### `Tabs.Tab`

An individual tab element. Tabs function like buttons, so they inherit
a lot of `Button` props.

**Props:**

- See inherited props: [Button](#button)
- `altSelection` - Whether the tab buttons select via standard select (color
  change) or by adding a white indicator to the selected tab.
  Intended for usage on interfaces where tab color has relevance.
- `icon: string` - Tab icon.
- `children: any` - Tab text.
- `onClick: function` - Called when element is clicked.

### `Tooltip`

A boxy tooltip from tgui 1. It is very hacky in its current state, and
requires setting `position: relative` on the container.

Please note, that [Button](#button) component has a `tooltip` prop, and
it is recommended to use that prop instead.

Usage:

```jsx
<Tooltip position="bottom" content="Box tooltip">
  <Box position="relative">Sample text.</Box>
</Tooltip>
```

**Props:**

- `position?: string` - Tooltip position. See [`Popper`](#Popper) for valid options. Defaults to "auto".
- `content: string` - Content of the tooltip. Must be a plain string.
  Fragments or other elements are **not** supported.

## `tgui/layouts`

### `Window`

A root-level component, which draws the window chrome, titlebar, resize
handlers, and controls the UI theme. All tgui interfaces must implement
it in one way or another.

Example:

```jsx
<Window theme="hackerman">
  <Window.Content scrollable>Hello, world!</Window.Content>
</Window>
```

**Props:**

- See inherited props: [Box](#box)
- `className: string` - Applies a CSS class to the element.
- `theme: string` - A name of the theme.
  - For a list of themes, see `packages/tgui/styles/themes`.
- `title: string` - Window title.
- `width: number` - Window width.
- `height: number` - Window height.
- `canClose: boolean` - Controls the ability to close the window.
- `children: any` - Child elements, which are rendered directly inside the
  window. If you use a [Dimmer](#dimmer) or [Modal](#modal) in your UI,
  they should be put as direct childs of a Window, otherwise you should be
  putting your content into [Window.Content](#windowcontent).

### `Window.Content`

Canonical window content, which is usually the main target of window focus.
Can be scrollable.

**Props:**

- See inherited props: [Box](#box)
- `className: string` - Applies a CSS class to the element.
- `fitted: boolean` - If true, removes all padding.
- `scrollable: boolean` - Shows or hides the scrollbar.
- `children: any` - Main content of your window.