# TerraUI

> Tactile React Native components (@terratcg/ui) for iOS and Android: raised keys, wells and shells with a typed theme. Every page below is Markdown; append .md to any docs URL.

TerraUI is React Native for iOS and Android, not web React. Follow these rules before writing code with it:

- **Versions:** `react ~19.3.0`, `react-native ~0.88.0` and `react-native-screens ~4.30.0`. Expo is optional.
- **Style props, not `className`:** style through each component's props and React Native's `style` prop. There is no CSS and no class name.
- **`onPress`, not `onClick`:** every pressable control takes `onPress`.
- **Text inside text components:** put every string inside a text component, such as `ButtonText`, `Text`, `RowTitle` or `NoticeTitle`. A bare string inside a `Button` or a `View` does not render.
- **One `ThemeProvider`, one `OverlayHost`:** mount each once, at the root of the app, with `OverlayHost` inside `ThemeProvider` and after your navigator. Dialogs, menus and toasts open through them, from anywhere.
- **Native first:** import from `@terratcg/ui`, never a web component library. Haptics, sounds, icons and navigation stay in your app.

## Docs

- [Action tray](https://ui.terratcg.app/docs/action-tray.md): A fixed bottom tray for a screen's essential figures and its confirming action. Compose it from ActionTrayNotice, ActionTrayRow and ActionTrayDetails.
- [Avatar](https://ui.terratcg.app/docs/avatar.md): A round portrait on the accent fill that falls back to an initial when there is no photo to show.
- [Badge](https://ui.terratcg.app/docs/badge.md): A small pill label for a category, a count or a status. Quiet by default.
- [Button](https://ui.terratcg.app/docs/button.md): A raised key that runs an action when pressed. Compose its label with ButtonText and an optional ButtonIcon.
- [Card](https://ui.terratcg.app/docs/card.md): A generic content surface with shallow depth. It holds content and is not meant to stand in for your app's own signature objects.
- [Cell](https://ui.terratcg.app/docs/cell.md): One pocket in a dense grid or shelf. Quiet framing keeps the art inside as the subject.
- [Compatibility](https://ui.terratcg.app/docs/compatibility.md): The React, React Native and react-native-screens versions TerraUI supports, the platforms it targets, and how its versions move.
- [Counter](https://ui.terratcg.app/docs/counter.md): A count against its total, such as "142 / 200". A bold accent count over a muted total.
- [Dialog](https://ui.terratcg.app/docs/dialog.md): A centred plate over a dimmed page that asks before an action, or says something to know. Open one from anywhere with showDialog.
- [Field](https://ui.terratcg.app/docs/field.md): One form field. A Label, an Input and an optional FieldMessage stacked together, sharing the field's invalid and disabled state.
- [Header bar](https://ui.terratcg.app/docs/header-bar.md): The plastic shell a navigator lays behind its native title and buttons. It is a surface slab over a hairline that casts its lift onto the page.
- [Icon button](https://ui.terratcg.app/docs/icon-button.md): A square Button for a single icon, for actions that a glyph names on its own. It always carries an accessibility label.
- [Getting started](https://ui.terratcg.app/docs.md): Install @terratcg/ui, mount ThemeProvider and OverlayHost once at the root, and press your first Button.
- [Input](https://ui.terratcg.app/docs/input.md): A native text input in a recessed well. It is a plain React Native TextInput, with the value, keyboard and events left to the platform.
- [Licence](https://ui.terratcg.app/docs/licence.md): TerraUI is proprietary and free to use, commercial apps included. You may not modify, redistribute or resell it.
- [Material](https://ui.terratcg.app/docs/material.md): TerraUI's controls are molded plastic lit from above. Raised keys travel onto their edge, surfaces are shells, and wells are cut into them.
- [Menu](https://ui.terratcg.app/docs/menu.md): A popover of actions or choices beside the control that opened it. Open one from anywhere with showMenu.
- [Notice](https://ui.terratcg.app/docs/notice.md): Empty, error and informational states composed from an icon, a title, a description and actions. InlineNotice is the one-line status beside content.
- [OverlayHost](https://ui.terratcg.app/docs/overlay-host.md): The one layer where every Dialog, Menu and toast appears, above native sheets. Mount it once at the root; open overlays from anywhere.
- [Progress](https://ui.terratcg.app/docs/progress.md): A pill track cut into the surface with a raised accent bar riding in it. Counter writes the numbers beside it.
- [Refresh control](https://ui.terratcg.app/docs/refresh-control.md): The platform's pull-to-refresh in the theme accent. Pass it as a list's refreshControl.
- [Row](https://ui.terratcg.app/docs/row.md): One line of a list, with a leading element, its content and an optional trailing control. A pressable row is a button.
- [Search field](https://ui.terratcg.app/docs/search-field.md): An Input with the magnifier leading it and a clear key while there is text, on the keyboard's search key. Clearing keeps the caret in the field.
- [Section](https://ui.terratcg.app/docs/section.md): Structure for a page of grouped content. SectionHeader heads a group, and Divider marks where one group ends.
- [Selectable cell](https://ui.terratcg.app/docs/selectable-cell.md): A quiet cell for picking items in dense grids and rows. Selection reads through its stroke and a check chip, protection through a dashed frame and a text badge.
- [Shelf](https://ui.terratcg.app/docs/shelf.md): A titled horizontal strip of pockets, such as recent items or favourites. Only a heading and spacing frame it, so the items stay the subject.
- [Shutter](https://ui.terratcg.app/docs/shutter.md): The capture key, a large round console face raised over its edge. Its inner ring reads as a shutter on any ground, a camera preview included.
- [Skeleton](https://ui.terratcg.app/docs/skeleton.md): A quiet placeholder shape in the size of what is loading. Still on purpose, with no shimmer.
- [Spinner](https://ui.terratcg.app/docs/spinner.md): The platform's activity indicator in the theme accent, for a wait without a known end.
- [Stat](https://ui.terratcg.app/docs/stat.md): Figures at a glance, in three forms. StatRow is a panel of counters, StatPill a compact resource counter and StatLine one labelled value in a list.
- [Switch](https://ui.terratcg.app/docs/switch.md): An on and off key that slides in a recessed slot. Use SwitchRow in a settings list, so a press anywhere on the row flips it.
- [Tab bar](https://ui.terratcg.app/docs/tab-bar.md): A quiet bottom deck of destinations around one raised central action. It only presents, so your navigator owns the routes and the selection.
- [Task](https://ui.terratcg.app/docs/task.md): One task on a quiet content surface. Its title, tag and reward sit over its progress; your app owns the progress and the claim.
- [Text](https://ui.terratcg.app/docs/text.md): Native text with the theme's type roles and semantic tones. Every word TerraUI draws goes through it.
- [ThemeProvider and feedback](https://ui.terratcg.app/docs/theme-provider.md): ThemeProvider hands every component its theme and an optional feedback handler, where your app plays its own haptics and sounds.
- [Theming](https://ui.terratcg.app/docs/theming.md): Start from the default theme and override what your brand needs with createTheme. Every token, the colour pairs that must pass WCAG AA, and a custom theme.
- [Toast](https://ui.terratcg.app/docs/toast.md): A short message that slides in from the top of the window, one at a time. Open one from anywhere with showToast.