# Window

> The root of every Tarve app: a native OS window with size, position and theme.

- Category: [Window & layout](https://tarve.dev/docs.md#layout)
- Import: `import { Window } from "@tarve/core";`
- Props type: `WindowProps`
- Source: [packages/core/src/components/window.ts:83](https://github.com/omarcosr/tarve/blob/main/packages/core/src/components/window.ts#L83)

## Usage

```tsx title="Window.tsx"
import { Column, Text, Window, createApp, darkTheme } from "@tarve/core";

function App() {
  return (
    <Window title="Notes" width={640} height={320} minWidth={480} minHeight={240} position="center" theme={darkTheme}>
      <Column flex={1} padding={24} gap={8}>
        <Text size={24} weight={700}>Hello from Tarve</Text>
        <Text>This is a native window. No browser involved.</Text>
      </Column>
    </Window>
  );
}

const app = createApp(App);
await app.ready;
await app.closed;
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `activation` | `WindowActivation` | — | How the window takes the foreground (Windows): `"normal"` (default) when shown or clicked; `"never"`, for a dock, menu or overlay that must not take the keyboard from the app in use; `"whileEditing"`, like `"never"` until a click focuses an editable `Input`/`TextArea`: the window then activates to receive typing, and when that field blurs it stops being activatable and hands the foreground back to the window that had it. Elsewhere the window only opens without activating. Set when the window opens. |
| `backdrop` | `WindowBackdrop` | — | See through the window: `transparent` shows the desktop and windows behind it, `blur` blurs them (Acrylic on Windows, the system blur on macOS and KDE), `mica` and `acrylic` are the Windows 11 materials (`blur` elsewhere). The window background defaults to transparent; give it (or any box) an alpha colour to tint. Set when the window opens. Where the system or renderer has no alpha (Vello/DX12 on Windows, X11 without a compositor, the CPU renderer on Wayland and macOS) the window is opaque, its background drawn without alpha. Mica tints the desktop wallpaper, not the windows behind; `blur` and `acrylic` blur those. As for the system's own windows, Mica and Acrylic turn solid while the window is inactive (`blur` stays), and all three are solid while Windows "Transparency effects" is off (`app.inspect().transparencyEffects`; `app.onEvent` gets a `transparencyEffects` event when it changes). The material is light or dark after the window background's lightness (the app theme), not the system theme. |
| `chrome` | `WindowChrome` | — | What a `frameless` window keeps of the system frame on Windows 11: `"system"` (default) the rounded corners and the 1 px border (the root's `borderColor`), `"none"` square corners and no border, for shapes the app draws itself (a dock, a pill, an overlay). Set when the window opens. |
| `desktopWidget` | `DesktopWidget` | — | Make the window a desktop widget, `columns` × `rows` cells: frameless, below every window (unless `level` says otherwise) and off the taskbar. Windows: sized to the desktop icon grid; when dragged (give it a `dragRegion`) it drops into the nearest cells free of icons, and icons that land under it are moved out. Linux (X11; XWayland on a Wayland session): cells of a typical icon, 80 × 100, on every workspace; no icon grid to follow. `width`/`height` are ignored; `position` is where it first looks for room. |
| `frameless` | `boolean` | — | No native frame or title bar, without needing a `TitleBar`. Pair with a `dragRegion` to move it. |
| `height` | `number` | — |  |
| `level` | `WindowLevel` | — | Stacking order; `alwaysOnBottom` keeps the window under every other one, even when clicked or shown. Can change while the app runs. |
| `maximized` | `boolean` | — | Opens maximized; `width`/`height`/`position` are the bounds it restores to. A remembered window state wins. |
| `minHeight` | `number` | — |  |
| `minWidth` | `number` | — |  |
| `onCloseRequest` | `(event: WindowCloseRequestEvent) => void` | — |  |
| `opacity` | `number` | — | The whole window's opacity, 0–1 (Windows and X11), applied by the system compositor. Can change while the app runs. |
| `position` | `WindowPosition` | — |  |
| `resizable` | `boolean` | — |  |
| `skipTaskbar` | `boolean` | — | Keep the window off the taskbar and out of Alt+Tab (Windows) or the task switcher and pager (Linux, X11). |
| `theme` | `ThemeDefinition` | — |  |
| `title` | `string` | — |  |
| `visible` | `boolean` | — | `false` opens the window hidden (nothing flashes on screen); `app.show()` or `app.activate()` shows it later. Default `true`. |
| `width` | `number` | — |  |

### Inherited from `ViewProps`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `Style["align"]` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it first appears (HTML `autofocus`); interactive views only (Pressable). |
| `children` | `BindableChild` | — |  |
| `dismissOnOutside` | `boolean` | — | A press outside the box fires `onOutsideClick` instead of reaching what is under it (light dismiss). Works on portals and in-flow boxes; an open portal wins. |
| `dragRegion` | `boolean` | — |  |
| `flex` | `number \| string` | — | CSS `flex`: `1` is `1 1 0`; strings take any CSS value, e.g. `"1 1 176px"`. |
| `focusable` | `boolean` | — |  |
| `gap` | `number` | — |  |
| `justify` | `Style["justify"]` | — |  |
| `onOutsideClick` | `() => void` | — | With `dismissOnOutside`: a press (or right click) outside the box. |
| `padding` | `Style["padding"]` | — |  |
| `portal` | `boolean` | — |  |
| `style` | `Reactive<Style>` | — | Values may be signals: setting one restyles this box without a render. |
| `windowAction` | `"minimize" \| "toggleMaximize" \| "toggleFullscreen" \| "close"` | — |  |

## Common props

Shared by every component (descriptions: https://tarve.dev/docs.md#common-props): `class`, `className`, `dropTarget`, `fileDropTarget`, `highlight`, `id`, `key`, `motionFrom`, `onDragEnter`, `onDragLeave`, `onDrop`, `onFileDragEnter`, `onFileDragLeave`, `onFileDrop`, `onHighlight`, `onPaste`, `onPointerLeave`, `onPointerMove`, `onSize`, `onTransitionEnd`, `rovingGroup`.

## Types

```ts title="BindableChild"
type BindableChild = Child | Signal<unknown> | BindableChild[];
```

```ts title="DesktopWidget"
interface DesktopWidget { columns: number; rows: number }
```

```ts title="Reactive"
type Reactive<S> = { [K in keyof S]: S[K] | Signal<Exclude<S[K], undefined>> };
```

```ts title="WindowActivation"
type WindowActivation = "normal" | "never" | "whileEditing";
```

```ts title="WindowBackdrop"
type WindowBackdrop = "none" | "transparent" | "blur" | "mica" | "acrylic";
```

```ts title="WindowChrome"
type WindowChrome = "system" | "none";
```

```ts title="WindowCloseRequestEvent"
interface WindowCloseRequestEvent {
  readonly defaultPrevented: boolean;
  preventDefault(): void;
}
```

```ts title="WindowLevel"
type WindowLevel = "normal" | "alwaysOnTop" | "alwaysOnBottom";
```

```ts title="WindowPosition"
type WindowPosition = WindowPositionPreset | { x: number; y: number; physical?: boolean };
```

Next: [TitleBar](https://tarve.dev/docs/components/TitleBar.md)

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/components/Window · Index for agents: https://tarve.dev/llms.txt
