---
title: Choose an API
description: Pick the smallest abstraction that fits what you want to put on the desktop.
---

Pick an API by what you want to display. The lowest-level Finder command is
rarely the right starting point.

| What you're building | Start here | Why |
| --- | --- | --- |
| A moving game piece or changing visual state | [Stage & Sprite](/docs/reference/components/stage) | Prepare variants once, then move warm files. |
| A score or counter | [Score](/docs/reference/components/score) | Reuse prepared digit artwork. |
| A banner, label, or help panel | [Text](/docs/reference/components/text) | Lay lines out once as tiles; show or hide the block. |
| Keyboard help or a pause screen | [Overlays](/docs/reference/components/overlay) | Reuse the existing help display and lifecycle. |
| An editor or conversation transcript | [Text surfaces](/docs/guides/text-surfaces) | Separate text state from glyph allocation and placement. |
| Responsive positioning | [Layout](/docs/reference/components/layout) | Derive positions from the current desktop geometry. |

## Own state in your application

FileDOM renders your state. Game rules, note persistence, network connections,
and editor commands stay in your code, where you can test them without moving
real Desktop files. [Hooks](/docs/reference/hooks) connect input and desktop geometry
to that model.

Changing artwork works by switching which prepared file is visible, so a Sprite
never updates a file's custom icon frame by frame. Read the
[rendering model](/docs/learn/rendering-model) before allocating your first pool.

## Choose the lifecycle deliberately

A bare `createRoot()` owns its rendered tree. Unmounting it removes the files it
rendered and restores any wallpaper or view options it changed, but it does not
hide or reveal the user's Desktop items or touch the Dock and menu bar. For a
full desktop takeover, use the [session API](/docs/reference/react-api#startsession),
which adds those steps. Under Finder Mode, the signed app hides and restores the
Desktop itself and the session skips its own copy of that work.

:::warning[One desktop, shared native state]
Only one root or session can be active in a process; a second one is rejected
before it touches the desktop. Covers, input, view settings, and the visible
desktop are shared native state, so a root does not behave like a separate
browser tab or canvas.
:::

## Reach lower only when you need to

The [system API](/docs/reference/system) exposes native operations. Calling it
directly makes you responsible for ordering, ownership, and cleanup, so prefer
the component lifecycle unless you are building a primitive the library lacks.

Next, follow [Pong](/docs/examples/pong) for a small game. To extend FileDOM itself,
read [architecture](/docs/reference/architecture) and the
[host runtime](/docs/reference/host-runtime).