# @opengovsg/oui

> Open Government Products Singapore design system. React components built on react-aria-components, distributed as the @opengovsg/oui npm package and themed via @opengovsg/oui-theme.

Install: `pnpm add @opengovsg/oui @opengovsg/oui-theme tailwindcss react-aria-components motion`

Import: `import { Button } from "@opengovsg/oui"`

## Getting started

- [Installation](https://oui.open.gov.sg/docs/getting-started/installation.md): How to install and set up OUI in your project
- [Next.js](https://oui.open.gov.sg/docs/getting-started/next.md): How to install and set up OUI in a Next.js project
- [Registry (shadcn-style)](https://oui.open.gov.sg/docs/getting-started/registry.md): Install components as local source via the shadcn CLI for full customization.
- [Theming](https://oui.open.gov.sg/docs/getting-started/theming.md): How to customize the OUI theme to match your product's branding
- [Vite](https://oui.open.gov.sg/docs/getting-started/vite.md): How to install and set up OUI in a Vite project

## Guides

- [Forms](https://oui.open.gov.sg/docs/guides/forms.md): How to compose, validate, and submit forms with OUI — including React Hook Form + Zod.

## Form & Input

- [AttachmentField](https://oui.open.gov.sg/docs/components/attachment-field.md): Not exported by OUI — use FileDropzone for file uploads.
- [Button](https://oui.open.gov.sg/docs/components/button.md): Used to trigger an action or event
- [Calendar](https://oui.open.gov.sg/docs/components/calendar.md): A calendar displays one or more date grids and allows users to select a single date.
- [Checkbox](https://oui.open.gov.sg/docs/components/checkbox.md): A checkbox allows a user to select multiple items from a list of individual items, or to mark one individual item as selected.
- [CheckboxGroup](https://oui.open.gov.sg/docs/components/checkbox-group.md): A checkbox group lets users select one or more options from a list. For single-select, use RadioGroup; for a dropdown, use Select.
- [ComboBox](https://oui.open.gov.sg/docs/components/combo-box.md): A type-ahead select that filters options as the user types. For non-filterable dropdowns, use Select; for multi-select, use TagField.
- [DateField](https://oui.open.gov.sg/docs/components/date-field.md): A date field allows users to enter and edit date and time values using a keyboard. Each part of a date value is displayed in an individually editable segment.
- [DatePicker](https://oui.open.gov.sg/docs/components/date-picker.md): A date picker combines a DateField and a Calendar popover to allow users to enter or select a date and time value.
- [DateRangePicker](https://oui.open.gov.sg/docs/components/date-range-picker.md): A date range picker combines two DateFields and a RangeCalendar popover to allow users to enter or select a date and time range.
- [Field](https://oui.open.gov.sg/docs/components/field.md): Primitives for composing accessible form fields with labels, descriptions, errors, and input grouping. Most callers should use a higher-level component (TextField, etc.) instead.
- [FileDropzone](https://oui.open.gov.sg/docs/components/file-dropzone.md): A component that allows users to upload files via drag-and-drop or file selection.
- [MultiSelect](https://oui.open.gov.sg/docs/components/multi-select.md): Not exported by OUI — use TagField for multi-select with filtering.
- [NumberField](https://oui.open.gov.sg/docs/components/number-field.md): A field that allows users to enter a number and increment or decrement the value using stepper buttons.
- [PhoneNumberField](https://oui.open.gov.sg/docs/components/phone-number-field.md): A phone number field allows users to enter and edit phone numbers using a keyboard.
- [RadioGroup](https://oui.open.gov.sg/docs/components/radio-group.md): A radio group lets users select one option from a mutually exclusive list. For multi-select, use CheckboxGroup; for a dropdown, use Select.
- [RangeCalendar](https://oui.open.gov.sg/docs/components/range-calendar.md): A range calendar displays one or more date grids and allows users to select a contiguous range of dates.
- [SearchField](https://oui.open.gov.sg/docs/components/search-field.md): Free-text search with a clear button. For selecting from a constrained list, use ComboBox.
- [Select](https://oui.open.gov.sg/docs/components/select.md): A collapsible dropdown for choosing one option. For type-ahead filtering, use ComboBox; for multi-select, use TagField.
- [SingleSelect](https://oui.open.gov.sg/docs/components/single-select.md): Not exported by OUI — use ComboBox (filterable) or Select (non-filterable).
- [TagField](https://oui.open.gov.sg/docs/components/tag-field.md): A type-ahead input for selecting multiple items from a list, rendering each as a removable tag. For single-select with filtering, use ComboBox.
- [TextAreaField](https://oui.open.gov.sg/docs/components/text-area-field.md): A multi-line text field that allows a user to enter a plain text value with a keyboard.
- [TextField](https://oui.open.gov.sg/docs/components/text-field.md): A text field that allows a user to enter a plain text value with a keyboard.
- [TimeField](https://oui.open.gov.sg/docs/components/time-field.md): A time field allows users to enter and edit time values using a keyboard. Each part of a time value is displayed in an individually editable segment.
- [Toggle (Switch)](https://oui.open.gov.sg/docs/components/toggle.md): A toggle is used to switch between two possible states, commonly enabled or disabled states.

## Layout & Navigation

- [Accordion](https://oui.open.gov.sg/docs/components/accordion.md): A vertically stacked list of headers that reveal or hide associated sections of content.
- [Breadcrumbs](https://oui.open.gov.sg/docs/components/breadcrumbs.md): Displays the current location within the hierarchy. It allows users to go back higher in the hierarchy.
- [GovtBanner](https://oui.open.gov.sg/docs/components/govt-banner.md): The official Singapore Government masthead, pinned at the top of the page with an expandable "How to identify" panel. For system messages use Banner.
- [Link](https://oui.open.gov.sg/docs/components/link.md): A link allows users to navigate to different pages or resources.
- [Navbar](https://oui.open.gov.sg/docs/components/navbar.md): A responsive navigation header positioned on top side of the page that has affordances for branding, links, actions, etc.
- [Pagination](https://oui.open.gov.sg/docs/components/pagination.md): Displays a page range and lets users navigate between pages of content. For infinite scroll, consider a "Load more" button pattern instead.
- [Sidebar](https://oui.open.gov.sg/docs/components/sidebar.md): Displays a list of links or actions to navigate between different sections.
- [Tabs](https://oui.open.gov.sg/docs/components/tabs.md): Organizes content into multiple panels and lets users switch between them. For page-level navigation, use a nav element or breadcrumbs instead.

## Overlays

- [Menu](https://oui.open.gov.sg/docs/components/menu.md): A dropdown of actions triggered from a button or other element. For value selection, use Select or ComboBox.
- [Modal](https://oui.open.gov.sg/docs/components/modal.md): A modal is an overlay element which blocks interaction with elements outside it.
- [Tooltip](https://oui.open.gov.sg/docs/components/tooltip.md): A tooltip displays a brief description of an element on hover or focus.

## Feedback

- [Banner](https://oui.open.gov.sg/docs/components/banner.md): Communicates a prominent system-level message at the top of the screen, regardless of the user's place in the application.
- [Infobox](https://oui.open.gov.sg/docs/components/infobox.md): A non-dismissable callout for important information surfaced at a higher hierarchy than inline help text. Not triggered by user action.
- [Spinner](https://oui.open.gov.sg/docs/components/spinner.md): An animated indeterminate loading indicator. For a content-shaped placeholder use Skeleton; for a determinate task use Progress.
- [Toast](https://oui.open.gov.sg/docs/components/toast.md): A toast is a non-modal, unobtrusive, and time-limited notification that provides succinct feedback about an action.

## Display

- [Avatar](https://oui.open.gov.sg/docs/components/avatar.md): A visual representation of a user or entity in the product.
- [Badge](https://oui.open.gov.sg/docs/components/badge.md): A static visual indicator which can be used to represent numeric values, statuses, labels.

## Optional

- [llms-full.txt](https://oui.open.gov.sg/llms-full.txt): All docs concatenated into a single file for bulk ingestion.