Skip to main content

Display

AppWindow

A live piece of interface framed as an application's window: a title bar with a label (such as the file the demo lives in) and actions at its end, the working content inside, and the Ouro HX components it is built from along its foot. Its edge is a real border, so it holds in forced colours.

kettle.tsx
Built with
  • Switch
  • Button

On this site

This site's own pages use AppWindow too. Open one with X-ray pointing it out: The Nautilus's story

Install

Hand it to your agent
Add AppWindow from Ouro UI to this app. Read https://ui.ouroboros.bot/docs/app-window.md first and follow it.

Or by hand. Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):

npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.344

Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):

npx shadcn@latest add ourostack/ouro-ui/app-window#v1.3.344

Or, with the @ouro namespace set up:

npx shadcn@latest add @ouro/ouro-base @ouro/app-window

Its tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):

npx shadcn@latest add ourostack/ouro-ui/app-window#v1.3.344 ourostack/ouro-ui/app-window-tests#v1.3.344
import { AppWindow } from "@/components/ouro/app-window/app-window";

Paths use shadcn's default @/ alias; the CLI rewrites them to yours.

Example

<AppWindow title="tea.tsx" actions={<Button variant="plain" size="sm">Code</Button>} builtWith={["Checklist", "Button"]}>
  <TeaSteps />
</AppWindow>

Use instead when

  • Use Card instead when the content is a card in your own interface, not a demo of one, and CodeBlock instead to show the code rather than the working interface.

Props

Type: AppWindowProps.

actions
Type: ReactNode
At the end of the title bar, such as a Code button that shows the demo's source.
builtWith
Type: readonly string[]
The Ouro HX components the content is built from, each an outline Badge in a list along the window's foot, after the builtWithLabel. With none, the window has no foot.
builtWithLabel
Type: string
Default: "Built with"
The foot's label, which also names its list, for another language.
children
Type: ReactNode
The live content: the working interface the window frames.
className
Type: string
Layout only: margins, width (mt-8, max-w-xl). Appearance classes warn in development.
inset
Type: boolean
Default: true
Padding round the content. false runs the content edge to edge, for a picture, a map or a chart.
ref
Type: Ref<HTMLDivElement>
Reaches the rendered element.
title (required)
Type: ReactNode
The title bar's label, such as the file the demo lives in (tea.tsx): small, muted and monospace, cut short with an ellipsis when the bar is too narrow.

Native attributes

Also accepts the attributes in React's HTMLAttributes (id, aria-*, event handlers), passed to the rendered element, except those named on this page.

Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

  • components: Not a prop. The components are builtWith: <AppWindow builtWith={["Button", "Checklist"]} />.
  • footer: Not a prop. The foot lists builtWith: <AppWindow builtWith={["Button", "Checklist"]} />.
  • label: Not a prop. The bar's label is title: <AppWindow title="tea.tsx" />.
  • padded: Not a prop. The padding is inset: <AppWindow inset={false} /> runs the content edge to edge.
  • uses: Not a prop. The components are builtWith: <AppWindow builtWith={["Button", "Checklist"]} />.

className is for layout only

Pass margins, width and grid placement (mt-4, w-full, col-span-2).

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (hover:, sm:) and any ! are removed, it starts with bg-, text-, border-, rounded-, shadow-, font-, ring-, from-, via-, to-, fill- or stroke-, or is border, rounded, shadow or ring, or has a dark: variant. Text wrapping, overflow and table layout classes (text-wrap, text-ellipsis, border-collapse) are layout and do not warn.

Alignment classes (text-center) warn too: set alignment on a parent element.