A kit decides what your templates look like. It maps RageKit's elements (Button, Slider,
Tabs, …) to components written in Slint, the toolkit that draws the UI, and
it can add elements of its own.
Templates don't change when you switch kits: every kit accepts the same attributes for the core
elements, so the same .rk file builds with any of them. You only need Slint if you write a kit.
See also: templates, getting started, dev mode.
| Kit | Look | Third-party code |
|---|---|---|
material (default) |
Slint's Material 3 library: Material buttons, cards and inputs | Slint's Material library (MIT), downloaded on the first build |
shadcn |
Dark zinc palette, 8 px radius, 1 px borders, in the style of shadcn/ui | none |
Material also acts as the fallback: if the active kit lacks a core element, or has no window component, Material's is used. That's why its library is downloaded even when you use another kit.
Known rough edge: Material's slider can only be dragged by its thumb.
In project.yml:
ragekit:
backend: slint
kit: shadcnOr for one build, without editing the file:
vendor/bin/ragekit build --kit=material
vendor/bin/ragekit dev --kit=materialA kit name that isn't installed is an error listing the installed kits.
Every kit that provides a core element accepts exactly these attributes for it:
| Element | Attributes |
|---|---|
Label |
text, size (body, title, display) |
Button |
text, variant (default, secondary, outline, ghost, destructive), event onClick |
Entry |
value (two-way string), onSubmit (Return pressed); focus: (for ref) |
Checkbox |
text, checked (two-way bool) |
Slider |
value (two-way float), min, max (default 0 to 1) |
Select |
value (two-way string), options (list) |
Image |
source (image) |
Progress |
value (float, 0 to 1) |
Card |
title, contains other elements |
Separator |
(none) |
Switch |
text, checked (two-way bool) |
Textarea |
value (two-way string), placeholder, rows (int), maxRows (int), onSubmit (Return; Shift/Alt+Return adds a line); focus: (for ref) |
RadioGroup |
value (two-way string), options (list) |
Toggle |
text, pressed (two-way bool) |
Badge |
text, variant (default, secondary, outline, destructive) |
Avatar |
source (image), text (shown without an image), size (sm, md, lg) |
Alert |
title, text, variant (default, destructive) |
Skeleton |
width, height (int, pixels) |
Spinner |
size (sm, md, lg) |
Sidebar |
title, contains other elements |
NavList |
items (list), selected (two-way string) |
Breadcrumb |
items (list), event onSelect passing the clicked item (string) |
Pagination |
page (two-way int), pages (int) |
TabBar |
titles (list), selected (two-way int): used by <Tabs> in templates |
AccordionHeader |
title, open (bool), event onToggle: used by <Accordion> in templates |
Text |
text, variant (h1, h2, h3, h4, p, lead, large, small, muted, code, blockquote); also takes text styles, so it declares color, font-size, font-weight, horizontal-alignment (see ShadText). For markdown="true": a markdown bool prop and a styled property (styled-text, which the compiler sets to the parsed text and the component draws with a StyledText instead of its Text), and onLink: { callback: link-clicked, value: string }. Under a View's ContextMenu the compiler also sets menu: true and handles menu-requested(x, y) / forward-click(x, y) (window coordinates): the component puts a TouchArea over the StyledText that asks for the menu on a right-click and passes other clicks on (see ShadText) |
Dialog |
title, contains other elements, event onDismiss; the compiler sizes it to the whole window: draw the scrim, the centred panel, and call onDismiss on a scrim click or Esc (see ShadDialog) |
DropdownMenu |
text, variant (Button's), items (list), variants (list: default/destructive per item), event onSelect passing the picked index (int): used by <DropdownMenu> in templates |
ContextMenu |
items, variants and onSelect as DropdownMenu's, plus a public function open(x: length, y: length) that shows the list at that point (relative to the component, which the compiler puts at its View's top-left corner); it takes no room itself (width/height: 0px) |
Toast |
text: one toast; the compiler stacks them bottom-right of every window |
WindowControls |
maximized (bool), events onMinimize, onToggleMaximize, onClose: used by layouts |
Elements with a fixed size (Avatar, Skeleton, Spinner) should sit in a left-aligned row
(inherit HorizontalLayout with alignment: start): a fixed width directly in a column limits the
column's maximum width, and with it the window's.
A kit's Label component must inherit Slint's Text (directly or through another component): text
styles (color, fontSize, fontWeight, textAlign) are set on it directly.
A kit may give a core element extra attributes. A template that uses them then builds only with that kit.
Styles (see templates) change an element's size, margin and position, but how a kit draws its elements (colours, corners, hover effects) is the kit's own Slint code. To change that, copy the kit into your app:
ragekit eject # lists the kits you can eject
ragekit eject shadcn # copies it to kits/<your project's name>/ and uses it
ragekit eject shadcn brand # … named "brand"; --no-use copies without switching project.yml- The copy lands in
kits/<name>/andproject.ymlswitches to it (ragekit: kit: <name>; the rest of the file, comments included, stays as it was). - Its components are renamed after the new name (
ShadButton→GalleryButton), so the copy and the original never clash. The original stays installed, and Material is still the fallback for core elements a kit lacks. - From then on it's your app's code: edit its
.slintfiles freely (in shadcn, the colours and corner radius are one global block at the top ofshadcn.slint).ragekit devreloads kit edits. RageKit's later updates to the original kit don't reach the copy; itskit.ymlnotes where it came from. - Code a kit fetches (Material's
library/) isn't copied; the build fetches it again. Eject tells you the line to add to your.gitignore. - The name must be lowercase letters, digits and dashes, and not an installed kit's. Eject never
overwrites an existing
kits/<name>/. - Keep the core element contract when you edit, so your templates keep building.
A kit can provide elements that aren't in the core set. Templates use them with an XML namespace whose value is the kit's name:
<VStack xmlns:ui="icons">
<ui:ImageButton image="assets/play.svg" text="Play" onClick="play" />
</VStack>A kit is a folder with a kit.yml and one or more .slint files. This is a complete kit that
adds one element, an icon button:
kits/icons/
kit.yml
icons.slint
# kits/icons/kit.yml
name: icons
entry: icons.slint
elements:
ImageButton:
component: ImageButton
props:
image: image
text: string
events:
onClick: clicked// kits/icons/icons.slint
export component ImageButton inherits Rectangle {
in property <image> image;
in property <string> text;
callback clicked;
min-width: 72px;
min-height: 84px;
border-radius: 16px;
background: touch.pressed ? #4a5175 : touch.has-hover ? #3a405e : #2b2f45;
animate background { duration: 120ms; }
VerticalLayout {
padding: 12px;
spacing: 6px;
alignment: center;
Image {
source: root.image;
height: 36px;
image-fit: contain;
}
if root.text != "" : Text {
text: root.text;
horizontal-alignment: center;
}
}
touch := TouchArea {
clicked => { root.clicked(); }
}
}| Key | Meaning |
|---|---|
name |
The kit's name: what ragekit: kit: and template namespaces refer to. Required. |
entry |
The .slint file that exports the components, relative to the kit's folder. Required. |
elements |
Template tag → element definition (below). |
window |
The component every window inherits. Optional; Material's is used without it. |
libraries |
Slint libraries the kit imports: name: path, imported in Slint as "@name". |
fetch |
Third-party code to download into the kit's folder (below). |
Inside kit.yml, ${KIT} is the kit's folder and ${RAGEKIT} is RageKit's root. Other
${NAME} values are read from the environment; an unset one is an error.
elements:
Slider:
component: ShadSlider # exported from the entry file
props:
value: { type: float, twoWay: value_changed }
min: { type: float, property: minimum }
max: { type: float, property: maximum }
Button:
component: ShadButton
props:
text: string
variant: { type: string, enum: [default, secondary, outline, ghost, destructive] }
events:
onClick: clicked
Card:
component: ShadCard
props:
title: string
children: truecomponent: the Slint component the element becomes. Required.props: the attributes it accepts. Short formname: type, or a map:type:string,int,float,bool,list(a list of strings) orimage;property: the Slint property it sets, when it differs from the attribute's name;enum: the allowed literal values (templates can't bind enum attributes);twoWay: makes it an input (see below).
events: template attribute → Slint callback, e.g.onClick: clicked. When the callback fires, RageKit calls the template's handler; declare such a callback without arguments (callback clicked;). An event that hands the handler a value (a clicked item) is a map:onSelect: { callback: selected, value: string }withcallback selected(string);in Slint; the template then names just the method (onSelect="goTo"), which takes that one value.enables: <bool property>in that map sets the property totruewhen the template uses the event:onSubmit: { callback: submitted, enables: submit-on-return }lets a Textarea send on Return only when there's a handler for it.children: true: the element can contain other elements. Its component places them with Slint's@children.focus: <int property>: the element takesref="…", andScreen::focus()can give it the keyboard focus. The compiler binds the property to a number that changes on everyfocus('that-ref')(0 while another ref is asked for); the component focuses its input when it changes to more than 0:in property <int> focus-request; changed focus-request => { if (self.focus-request > 0) { input.focus(); } }. Entry and Textarea have it in both kits.
Templates can only use attributes listed under props and events (plus grow, when and
each, which every element has).
value: { type: float, twoWay: value_changed }in-out property <float> value;
callback value_changed(float);The component declares the property as in-out and a callback with one argument of the prop's
type. It calls the callback with the new value when the user changes it, and must not call it
when the value is set from PHP. RageKit binds the property to the screen's PHP property both ways.
image props take what Image's source takes (see templates.md, "Image"): a file path or
$assets->…, embedded when the app is built, or a string value bound from PHP (a registered
image, a file or a web URL), plus fallback="…" while a bound image is empty. In Slint the prop
is an in property <image>; an empty image has width == 0.
window: ShadWindowexport component ShadWindow inherits Window {
background: Shad.background;
default-font-size: Shad.font-size;
}Every screen's window inherits it, so it sets what applies to the whole window: background,
default font, colours. It must inherit Slint's Window (directly or through another component).
RageKit sets the window's title and its content.
Elements are placed in vertical and horizontal layouts. Give components sensible preferred and
minimum sizes; the layout stretches an element only when the template says grow="true".
A kit that builds on other Slint code declares it under fetch:. RageKit downloads it into the
kit's folder on the first build (and again when it doesn't match), so it doesn't need to be in your
repository. This is how the Material kit gets Slint's Material library:
fetch:
- git: https://github.com/slint-ui/slint.git
ref: v1.18.1
commit: 372cf0ee5577c3dfec309a45e7b778ba4e81b734 # what the tag must point to
path: ui-libraries/material/src # only this folder is kept
to: library
libraries:
material: ${KIT}/library/material.slintA single file works too, checked by its SHA-256:
fetch:
- url: https://example.com/icons.slint
sha256: <the file's SHA-256>
to: vendor/icons.slintto must be a path inside the kit's folder. Add the fetched folder to your .gitignore.
Fetching needs git (for git: entries) and network access the first time.
Every installed kit's fetch: runs on every build (it's a quick check once the files are
present), not only the active kit's.
A kit that provides core elements (Button, Label, …) under their core names replaces Material's
when it is the active kit. Core elements it doesn't provide still come from Material. Keep to the
attributes in the contract so templates stay portable.
RageKit finds kits in three places, in this order:
- RageKit's own
kits/*/kit.yml(material,shadcn); - your app's
kits/*/kit.yml, next toproject.yml; - Composer packages that declare a kit (below).
Two kits with the same name from different folders are an error. Name your kits so they can't
clash with RageKit's or with packages you install.
Put it in <project>/kits/<name>/ with its kit.yml. It's found automatically; nothing to add to
project.yml unless you make it the active kit.
Point extra.ragekit.kit at the package's kit.yml, relative to the package root:
{
"name": "acme/ragekit-icons",
"type": "library",
"extra": {
"ragekit": {
"kit": "kit.yml"
}
}
}Require the RageKit minor version the kit was written for ("ragekit/ragekit": "^0.3"): the kit
format and the core element contract may change between 0.x minor versions (see the CHANGELOG).
After composer require acme/ragekit-icons, the app's next build sees the kit. RageKit reads the
app's vendor/composer/installed.json, so the package must be installed in the app itself.
With ragekit dev, changes to a kit's kit.yml and .slint files reload the UI in place, like
template changes. A kit error is reported and the old UI stays. See dev mode.
Slint, which draws every kit, is available under three licenses: a royalty-free license, GPLv3, and a commercial license. Apps under the royalty-free license must show Slint attribution (for example an About screen with Slint's "AboutSlint" notice, or a "Made with Slint" badge where the app is downloaded). Read slint.dev/licensing before you ship.
The Material kit uses Slint's Material library, which is MIT-licensed. Kits you write are yours
to license, but third-party Slint code you fetch: keeps its own license.