Manual
Manual
Style sheets
How a UI document looks is kept in style sheets: CSS files, read by bevy_flair, that select a document's elements and say how they look and are laid out. This page covers what a sheet holds, the order sheets apply in, the Style Sheets panel and a rule's Inspector, how rules show in an element's Inspector, and a value set in the Inspector over a rule.
A sheet and what it styles
A style sheet is a .css file in your assets. Style Sheet in the Project panel's + menu makes one with example rules, and a new UI document comes with a sheet of its own beside it (see Make a document).
.button {
border-radius: 10px;
background-color: #f2c14e;
transition: background-color 0.15s;
}
.button:hover {
background-color: #ffd56e;
}
.low {
color: #e0574a;
}A document names the sheets it is styled by in its Inspector, under Style Sheets, in order (see The document's Inspector). Saved, a sheet is read again at once, and every document it styles is styled again, in the editor and in a game that is playing.
The theme
The project's theme is a sheet every document is styled by, beneath the document's own: colors and fonts said once for the whole game. Name it in Edit ▸ Project Settings… ▸ UI, under Theme. The controls the UI menu makes add their rules to the theme the first time one of a kind is made, and make ui/theme.css where the project has none (see Controls).
The order sheets apply in
Lowest first:
- The element's own values, as its document gives them.
- The theme's rules.
- The document's sheets, in the order its list names them: a later sheet's rule is above an earlier one's where they are as specific.
- What is set on the element over its sheets: a value the Inspector sets where a rule sets it (see A value set over a rule), and an image or a place your code gives an element.
Because an element's own values are beneath every rule, a rule that stops applying gives them back. A button the document makes yellow, which a sheet lights on :hover, is yellow again as the pointer leaves it.
Selectors
A rule selects elements by:
| Selector | Selects |
|---|---|
button, text, label, span | An element by its kind: a Button, a Text |
.name | An element with that class (see UI Classes) |
#Name | An element of that name, as the Hierarchy names it. Escape a space with a backslash: #Main\ Menu |
:root | A document's top element |
.a .b, .a > .b | An element inside another, or right under it |
And by its state, after a selector:
| State | While |
|---|---|
:hover | The pointer is over it |
:active | It is pressed |
:focus | It has focus: what a key or a gamepad presses |
:focus-visible | It has focus, and a key or a stick moved it there: where to draw a ring |
:checked | A toggle is on |
:disabled | It carries Bevy's InteractionDisabled marker; a disabled button is not pressed |
The engine gives some elements classes of its own as their state changes, beside the ones they have:
| Class | On | While |
|---|---|---|
touch | Every document's top | The game is on a phone, a tablet, or a browser on a touch screen, where a finger presses what you draw: .touch .button { padding: 16px 28px; }. Code can say otherwise with World.Ui.Touch |
rtl | Every document's top | The language shown is written right to left; see Right-to-left languages |
open | A dropdown | Its list is open |
under, centered | A dropdown's list | It is open under the dropdown, or in the middle of the screen |
dropdown-backdrop | The backdrop behind a centered list | Always |
HasClass in code sees these as well, though code neither adds nor takes them away.
Rules can be nested in another rule, and grouped in an @media group. A sheet can bring in another with @import, by its path as any file a sheet names is; see Paths in a sheet.
left and right in a sheet are left and right in every language. For a side that follows the language, the left margin in English and the right one in Arabic, write CSS's logical properties: margin-inline-start, padding-inline-end, inset-inline-start and the rest; see Right-to-left languages.
Properties
A rule sets what an element looks like and how it is laid out, by CSS names: the layout, display, flex-direction, justify-content, width, margin, padding, gap; the border, border, border-radius, outline; the fill, background-color, gradients and shadows; the text, color, font-size, font-family, text-align; translate, scale and rotate, and transform-origin, the point they turn and scale around; opacity; and visibility. A length is in px, %, vw, vh, vmin, vmax or auto, and calc() works.
A value can move to its next over a transition, which names each property that moves. transition: all is not read: list them, transition: background-color 0.15s, border-radius 0.15s. A rule can also play @keyframes.
Motion
A rule makes an interface move by what changes when a class does, and the transition it names. A game's code gives the class (see Classes from code); the sheet says how it looks on the way.
opacitydraws an element and everything under it see-through, from1as it is to0not at all, its background, borders, text, images and shadows together. An element under another with an opacity is faded by both. An element at0is still there and can be clicked; hide it too, as below. A UI material running your own shader is drawn as its shader says.visibilitygoes fromvisibletohiddenas its transition ends, and tovisibleas it starts, as in a browser, so a panel plays its closing transition before it is hidden. A hidden element is not drawn, cannot be clicked, and keys and a gamepad pass it by. As in CSS, an element that saysvisibleis shown inside a hidden one: for a part that should hide with its panel, such as the page of a tab that is picked, sayinherit.transform-originis the pointscaleandrotatework around:centerunless a rule says otherwise, a side,top, a corner,top right, or lengths from the left and the top,12px 50%. A list that unfolds from its field scales from itstop.
A panel that opens and closes:
.panel {
opacity: 0;
scale: 0.9;
visibility: hidden;
transition: opacity 0.2s, scale 0.25s cubic-bezier(0.34, 1.56, 0.64, 1), visibility 0.25s;
}
.panel.open {
opacity: 1;
scale: 1;
visibility: visible;
}A list of buttons that come in one after another, each a little later. backwards holds each at its start while it waits, and lets it go once it has played, so a hover's own transition works after:
@keyframes rise {
from { opacity: 0; translate: 0 24px; }
}
.menu .button { animation: rise 0.4s ease-out backwards; }
.menu .button:nth-child(2) { animation-delay: 0.08s; }
.menu .button:nth-child(3) { animation-delay: 0.16s; }A transition's timing is linear, ease, ease-in, ease-out, ease-in-out, cubic-bezier(), a curve past 1 for a little overshoot, steps() or linear().
A transition moves a color as a browser does: an element with no background given one on hover fades it in, with no grey on the way. A turn goes the shorter way round, and half a turn the way its angles go: from 45deg to 225deg clockwise, and back the other way.
Variables
A rule can say variables, --name: value;, and a property can use one, var(--name). The variables of a :root rule can be used by every element of a document. A var() takes a name alone: a second value after it, as a fallback, is not read, and the property is dropped.
:root {
--accent: #f2c14e;
}
.button {
background-color: var(--accent);
}Fonts
To draw text in a font of your own, put its .ttf or .otf file in your assets and name it in an @font-face rule by its path (Paths in a sheet). Then use the family that rule gives it:
@font-face { font-family: "Bytesized"; src: url("/fonts/Bytesized/Bytesized-Regular.ttf"); }
* { font-family: "Bytesized"; }A theme that does this draws every document's text in the font. A build packs each font a packed sheet names.
Text is smoothed at its edges. A pixel font draws with hard edges, letters and their text-shadow alike, with -bevy-font-smooth: none (anti-aliased is the default):
* { font-family: "Bytesized"; -bevy-font-smooth: none; }Its pixels stay square where the text is drawn at a whole multiple of the font's own pixel. Where the interface is scaled to a screen by some other amount, some of them come out a pixel wider than others; smoothed, they stay even but look softer.
Images
A rule gives an element an image by its path (Paths in a sheet), with background-image, background or -bevy-image. In a sheet in ui:
.panel { background-image: url("panel.png"); }
.flag { -bevy-image: url("/ui/flag.localized"); }The image is drawn as its import, with the settings its Inspector gives it, and a build packs each image a packed sheet names. A localized image shows the file of the language the game is in, and changes with it.
Paths in a sheet
A sheet names a file — an image, a font, a sheet it imports — as a web page's sheet does: from the sheet's own folder, or from your assets folder after a slash. In ui/menu.css, panel.png and /ui/panel.png both name ui/panel.png, and ../fonts/Round.otf names fonts/Round.otf. A package's sheet names its own package's files so, and another package's by their whole name, such as acme.demo://ui/frame.png. What the Style Sheets panel and the Inspector write into a sheet, they write from the assets folder, after a slash.
A sheet written before the engine moved to Bevy 0.20 named every file from the assets folder without the slash. Such a path is now read from the sheet's folder, so url("ui/panel.png") in ui/menu.css names ui/ui/panel.png: put a slash before it, or name it from the sheet's folder.
The Style Sheets panel
The Style Sheets panel lists the rules of the sheets in reach: those of the document open on its own and the project's theme, or the sheet picked in the Project panel. Open it from Window ▸ Style Sheets; it opens behind the Hierarchy as you open a document.
Each sheet is a heading with its rules under it, in the order they are written. A rule nested in another, or in an @media group, is a step in. A rule bevy_flair cannot read is shown faint and is skipped as the sheet is read. An @import, a group's condition and @keyframes are listed and edited in the sheet's text.
- Add a rule: type a selector in the sheet's Add new selector... box and press Enter or +. It is added at the sheet's end once bevy_flair reads it, and what is wrong with it is said under the box. As you type, the box offers the selectors of the element last picked on the canvas: its classes, its name, its kind, and each class with a state.
- Edit a rule: click it. The Inspector shows it (see A rule in the Inspector).
- Rename it with a double click. Right-click it for Rename, Duplicate, Delete, whose comment goes with it, and Open in Code Editor, which opens the sheet at the rule's line.
- Move a rule by dragging it before another beside it.
With a document open, each rule says at its right end how many of the document's elements it applies to now, with the states the canvas holds. The elements of the rule picked are outlined on the canvas in violet.
Each edit is written into the sheet at once, where it stands, and the rest of the file is left as it was, comments and all. Each is one step of Ctrl+Z.
A rule in the Inspector
A rule picked in the Style Sheets panel shows in the Inspector: its selector, its sheet and line, and Open, which opens the sheet in your code editor at the rule. Below them is every property a rule can set, in groups: Layout, Size, Position, Flex, Grid, Spacing, Border, Background, Image, Text, Transform and Other. A group's heading counts what the rule sets in it, and opens where it sets something.
A property the rule sets has a violet bar before its name, in full color. The rest are faint, at what each is where nothing sets it. Set a value and it is written into the rule:
- a keyword is picked from its words;
- a length is dragged in its unit, and the unit picked from a list;
- a number is dragged;
- a color is picked;
- anything else, and a value written as a variable or with
calc(), is typed.
A drag is written as it is let go of, and a box as it is left. A value bevy_flair does not read for the property is refused, and why is said under it. A side set of a shorthand the rule writes, such as margin: 4px 8px, is written in the shorthand.
Right-click a row for Unset, which takes the property out of the rule; Use Variable, which lists the variables whose value fits the property; and, for a property set to a variable, Remove Variable, which writes the variable's value in its place so it looks the same.
Variables in the Inspector
Variables comes first: the rule's own variables, each with a lime bar, then those of the :root rules of the sheets in reach. Each is edited where it is said, a color picked and anything else typed. Right-click one for Remove. The row at its foot adds a variable to the rule: its name, --name, its value, and +.
A property set to a variable shows the variable's name in lime and its value faint after it.
Rules in an element's Inspector
With a document open on its own, pick an element and its Inspector marks each value one of its sheets sets with a violet dot before its name. Rest the pointer on the name to see which rule sets it, where, and to what. The rule's value is what is drawn.
- Click the dot to pick the rule in the Style Sheets panel, which comes forward with the rule in sight, and change its value there.
- Ctrl+click it to open the sheet in your code editor at the rule.
From Style Sheets, after the element's sections, lists what its sheets set on it that it shows no row of its own for, such as a component the element does not carry: each property by its CSS name and the value the rule gives it.
To see the rules of a state, hold the element in it with the :hover, :focus, :active, :checked and .open buttons on the canvas's row, and the document's touch rules with its Phone button (see The canvas).
A value set over a rule
Change a value in an element's Inspector where a rule sets it, and the element's own value is set over the rule, for that element alone, as a style attribute is on a web page. What you set is what is drawn. The violet dot turns to a ring.
Click the ring for Revert to Rule, which draws the rule's value again, keeping the element's own value beneath it, or Go to the Rule. Making a color clear, with the × of a background's color, gives the rule back too.
The properties an element sets over its rules are kept in its UiInline component, by their CSS names, and saved with the document.
Classes from code
A game's code gives an element a class, or takes one away, one at a time and without garbage, and the element is styled again in the frame, with the sheet's transitions:
Health.ToggleClass("low", hitPoints < 20);See Classes.
In the Scripting API
- StyleSheetFiles: a
.cssfile. - FontFiles: the fonts a sheet names.
- UiSettings: the theme, in
settings/ui.json. - UiElement: an element's classes, changed from code.
