---
title: "As a standalone frontend"
description: "Two files, and no assumption about what rendered the page."
canonical: index.html
navigation-title: "Frontend"
---
# As a standalone frontend
- [Two shapes](#two-shapes)
- [What it needs of a browser](#what-it-needs-of-a-browser)
- [One contract across the layers](#one-contract-across-the-layers)
- [The namespace states ownership](#the-namespace-states-ownership)
- [Where to read on](#where-to-read-on)
- [Non-negotiable](#non-negotiable)
Two files, and no assumption about what rendered the page. Markup from PHP,
Twig, Fluid or a template string uses the class layer with no JavaScript.
The custom elements upgrade that markup where there is behaviour to add.
- [Quick start](quickstart.md)
- [Page layout](layout.md)
- [Stylesheets](stylesheets.md)
- [Components](components/index.md)
- [Controls](components/controls.md)
- [Content](components/content.md)
- [Data & machine output](components/data.md)
- [Media](components/media.md)
- [Navigation](components/navigation.md)
- [Forms](components/forms.md)
- [Overlays](components/overlays.md)
- [Documents](documents.md)
> [!TIP]
> [Quick start](quickstart.md) puts a working surface on a page from the package or
> the drop-in, before the reference below explains each part.
## Two shapes
**The drop-in**
Copy the directory somewhere public and link two files. Lit is in the
bundle, because a drop-in has nothing to share a copy with.
```html
```
**The package**
ESM with `lit` external, for a page that already has a bundler. A
second copy of Lit gives a consumer a second reactive-element registry,
and an element upgrades under the wrong one.
```bash
npm install @typo3/soul-frontend lit
```
```javascript
import '@typo3/soul-frontend';
import '@typo3/soul-frontend/dist/soul.css';
```
**`data-theme`**
- Type: "light" | "dark"
Forces a mode on a subtree. Put it on `` for a whole page, so the
browser's own scrollbars and form controls match. Without it, the
reader's system decides, and both modes work: they are one declaration.
**`soul-boot.js`**
- Type: script
- Required
A line or two, loaded **before** the stylesheet and **not** as a module.
It reads the stored choice and writes `data-theme` before the first
paint. `` then shows the active side, because it reads the
document.
With no choice it writes nothing, and that absence is the third state.
The page follows the machine, and the switch draws the mark for it. A
concrete mode in its place comes back to the switch as a choice the
reader never made.
Without it a switch still switches, but the next page forgets the choice.
The choice lives under `soul-theme`, which is `sds-theme`'s own
default too. To name another, set `data-key` on the tag and give the
element the same one.
**`soul.css`**
- Type: stylesheet
- Required
The tokens and the `sds-` class vocabulary, in one file. It has no
scope class: the link *is* the opt-in. That is what lets a bare `
` or
`
` take its style without a class from the editor.
**`soul-inline.css`**
- Type: stylesheet
The same sheet with the two families inside it as data URLs. For a page
that goes out as one file: a report, a review, a page under a host's
content security policy. Paste it into a `