Skip to content
AtlasOSFramework API
Browse the docs

Atlas.Ui

The QML module every Atlas app imports, with windows, pages, buttons, fields, lists, dialogs, charts and the style and services behind them; how to install it, check it and find a type.

Atlas.Ui is the QML module of Atlas controls. Every Atlas app imports it, so they all share one look, one set of keyboard and accessibility rules and one copy on disk. It is a QML module installed next to Qt's own, like Kirigami. Its URI is Atlas.Ui.

Install and import

Install the atlas-ui package (Fedora 44, Qt 6.11). It brings in the Material Symbols fonts (atlas-symbols-fonts), Kirigami, IBM Plex Sans and JetBrains Mono.

sudo dnf install atlas-ui

The module lives in Qt's QML directory (/usr/lib64/qt6/qml/Atlas/Ui/). An app writes import Atlas.Ui in QML and links nothing: the QML engine loads the plugin. There is no CMake package and no devel package.

import QtQuick
import Atlas.Ui

AtlasWindow {
    title: qsTr("Hello")
    visible: true

    AtlasPage {
        anchors.fill: parent
        title: qsTr("Hello")

        PrimaryButton {
            text: qsTr("Say hello")
            symbol: Symbols.WavingHand
        }
    }
}

Note

import Atlas.Ui wins over the QML files in an app's own directory. An app file named like an Atlas.Ui type (say SearchField.qml) is hidden by it. New Atlas.Ui types are named Atlas<Name> to keep clear of apps' names; see Compatibility.

Check the module at configure time

The app template fails the CMake configure with a plain message when the module is missing. qmlcachegen and qmllint find it in Qt's QML directory by themselves, so the app's <app>_qmllint target checks the app's QML against it.

if(NOT EXISTS "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_QML}/Atlas/Ui/qmldir")
    message(FATAL_ERROR "Atlas.Ui is not installed: dnf install atlas-ui")
endif()

Version rule

Atlas.Ui only ever adds API. An app that uses something added after 1.0.0 states the oldest version it works with in two places, and keeps them equal:

  • Requires: atlas-ui >= X.Y.Z (and BuildRequires) in the app's RPM spec, so dnf installs a new enough one;
  • ui: "X.Y.Z" in the app's app! call, so at startup an older Atlas.Ui, installed some other way, gives a plain error window instead of a broken one.

AtlasApp.uiVersion reports the installed version at run time. Each page says which version added its type (since).

Guides

  • Design rules: what every Atlas app does.
  • Style and theming: colours, spacing, radii, density, blur and text scale.
  • Motion: springs, reduced motion and the violet to sakura gradient.
  • Compatibility: the API contract and what it means for an app.
  • Accessibility: focus, roles, names, right-to-left and the framework's tests.

The types

Every type has a page. The groups below are the sidebar sections.

Windows and pages

  • AtlasWindow: The application window: blurred or opaque by the shared switch, remembers its size, and goes frameless with a header bar.
  • AtlasHeaderBar: The merged header of a frameless window: window menu, title, tools and window buttons.
  • AtlasWindowButtons: Minimise, maximise and close buttons drawn like the AtlasOS window decoration.
  • AtlasWindowChrome: Singleton with the desktop's caption-button layout and whether a global menu exists.
  • AtlasPage: A scrolling page with a large bold title and centred margins.
  • AtlasAboutPage: A ready-made About page for any app.
  • AtlasOnboarding: A setup scaffold: steps, one page at a time, Back, Skip and Next.
  • StatusBar: A slim bottom bar of cells such as line, column and encoding.
  • StatusBarItem: One cell of a status bar, optionally clickable or with a menu.

Buttons

Fields and pickers

Lists and tables

Feedback and status

  • InfoBanner: An inline info, warning or error banner with actions.
  • Toast: A short message that goes by itself.
  • AtlasProgressBar: A progress bar with indeterminate, paused and error states.
  • AtlasSpinner: A busy indicator.
  • AtlasPlaceholder: Skeleton bars shown while content loads.
  • AtlasEmptyState: What a list shows when it has nothing.
  • AtlasBadge: A small pill label for a status or count.
  • AtlasAvatar: A round picture of a person, with initials as the fallback.
  • AtlasStat: A figure with a label, a unit, a trend and a sparkline.
  • AtlasEdgeGlow: The violet-to-sakura glow for "the system is working for you now".
  • StatusHero: A big centred status: icon, headline, subtitle and actions.

Charts

Text and code

Layout

Style and motion

  • AtlasStyle: The design tokens: colours, spacing, radii, fonts, motion and density.
  • Appearance: The look switches every app shares: transparency, colour scheme, motion and text scale.
  • AtlasSpringAnimation: The Atlas spring for movement and size.
  • AtlasFocusRing: The keyboard focus outline.

Icons

  • Symbol: One Material Symbols icon.
  • Symbols: The singleton of every symbol's name.

Services

Validators

Pages