Mahina

About

Mahina is a production-quality component library built on top of Qt 6 and QML. Every component is written to pass the qmlsc AOT strict-mode compiler, uses the shared Theme singleton for consistent design tokens (colours, spacing, radii, typography), and is designed exclusively for keyboard-and-mouse desktop interactions.

Components are registered as a proper QML module (import Mahina) so they drop into any Qt 6 project with a single find_package call. No JavaScript runtime, no web view, no third-party dependencies — just native Qt rendering at full GPU speed.

Motivation

Mahina started as the UI layer for Qub, a desktop SQL editor built with Qt 6. The goal was a consistent, well-functioning interface — something that felt cohesive rather than a collection of one-off widgets. Qt's built-in QtQuick.Controls covers the basics, but a real application quickly exposes the gaps: no data grid, no command palette, no chart primitives, no diff viewer, no sidebar sections.

After building enough components for Qub, the potential became clear. Other projects were already in mind that would need the same foundations, so the scope grew deliberately — from a handful of purpose-built widgets into a library that could serve as the UI layer for any desktop application.

The result is shared here because others building with Qt 6 are likely running into the same gaps. Mahina won't be the right fit for every project, but if you are looking for a single, coherent component set — one that covers everything from a humble Badge to a full SpreadsheetGrid, all sharing the same theme tokens, interaction conventions and AOT-safe QML patterns — it might save you from reimplementing the same primitives from scratch.

The library was built iteratively with AI assistance. The AI-made column in the component table confirms which components were AI-generated. The Human-reviewed column tracks which ones have been manually verified in a running application.

Installation

Via FetchContent Recommended

No local setup required — CMake fetches and builds Mahina automatically at configure time:

include(FetchContent)
FetchContent_Declare(Mahina
    GIT_REPOSITORY https://github.com/ajunior/mahina.git
    GIT_TAG        v0.45.0
)
FetchContent_MakeAvailable(Mahina)

target_link_libraries(MyApp PRIVATE
    Qt6::Quick Mahina Mahinaplugin Mahinaplugin_init)

As a subdirectory

Clone the repo alongside your project and add it directly:

add_subdirectory(mahina)

target_link_libraries(MyApp PRIVATE
    Qt6::Quick Mahina Mahinaplugin Mahinaplugin_init)

As an installed package

cmake -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64 \
               -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build -j$(nproc)
cmake --install build

Then in your project's CMakeLists.txt:

find_package(Mahina REQUIRED)
target_link_libraries(MyApp PRIVATE Mahina::Mahina Mahina::Mahinaplugin)
qt_import_qml_plugins(MyApp)

Bundled assets

Mahina ships three font families as embedded Qt resources — no system installation required:

• Inter (variable, v4.0) — UI font used by all components via Theme.fontFamily
• JetBrains Mono (variable, v2.3) — monospace font used by code and terminal components via Theme.fontFamilyMono
• Phosphor Icons (six weights) — icon font used by the Icon component

Register them with QFontDatabase before loading the QML engine:

#include <QFontDatabase>

// Inter and JetBrains Mono (UI and mono fonts)
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/InterVariable.ttf");
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/JetBrainsMonoVariable.ttf");

// Phosphor Icons (all six weights)
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/Phosphor-Regular.ttf");
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/Phosphor-Thin.ttf");
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/Phosphor-Light.ttf");
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/Phosphor-Bold.ttf");
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/Phosphor-Fill.ttf");
QFontDatabase::addApplicationFont(":/qt/qml/Mahina/assets/fonts/Phosphor-Duotone.ttf");

QML import

Register the import path at runtime, then use any component with a single import:

// main.cpp
engine.addImportPath(QStringLiteral("qrc:/qt/qml"));

// any .qml file
import Mahina

Button {
    text:    "Hello, Mahina!"
    variant: Button.Variant.Filled
    onClicked: console.log("clicked")
}

MahinaExtras

MahinaExtras is an optional companion library that ships alongside Mahina and adds native C++ capabilities that are not achievable in pure QML. Mahina itself stays dependency-free and AOT-safe; extras are opt-in.

It is not built by default. Enable it at configure time:

cmake -B build -DMAHINA_EXTRAS=ON

Linking

Add the extras targets next to the main Mahina targets in your CMakeLists.txt:

target_link_libraries(MyApp PRIVATE
    Qt6::Quick
    Mahina           Mahinaplugin           Mahinaplugin_init
    MahinaExtras     MahinaExtrasplugin     MahinaExtrasplugin_init
)

SyntaxHighlighter

Attaches to any CodeEditor via its textDocument property and applies token-level syntax colouring in real time. The colour scheme follows GitHub's dark/light palette and switches automatically when darkMode changes.

import Mahina
import MahinaExtras

CodeEditor {
    id: editor
    language: "sql"

    SyntaxHighlighter {
        document: editor.textDocument
        language: editor.language
        darkMode: Theme.dark
    }
}

Supported values for language:

An empty or unrecognised language value is accepted — the highlighter applies no rules and the editor renders plain monochrome text.

Icons

Mahina bundles Phosphor Icons as embedded font assets — 900+ glyphs across six weights (Thin, Light, Regular, Bold, Fill, Duotone) with no external dependencies and zero network requests.

All glyph names are exposed through the Icons singleton as typed string constants. This avoids magic strings and gives you editor autocompletion:

import Mahina

Icon {
    name:  Icons.magnifyingGlass
    size:  24
    color: Theme.primary
}

The Icon component renders any glyph at any pixel size and color. The same Icons.* namespace is used everywhere an icon name is accepted — Button, NavigationRail, ContextMenu, and the rest all take an iconName property that resolves through Icons.

To browse available names, see the Icons component in the reference section below, or search for a specific icon using the component search above.

Theming

Every component in Mahina reads its colours from the Theme singleton. There are no hardcoded values inside components — swapping the palette in one place updates the entire UI instantly.

Default palettes

Mahina ships two built-in palettes: light and dark. The active mode is controlled by a single flag:

Theme.dark = true   // switch to dark
Theme.dark = false  // switch to light
Theme.dark = !Theme.dark  // toggle

All 262 components react to this change automatically with no additional wiring.

Custom color schema

Theme.load(obj) replaces any subset of tokens at runtime. You only provide the keys you want to change — everything else keeps the Mahina default. Mode-independent tokens (primary, success, warning, etc.) sit at the top level. Surface, border and text tokens that vary between light and dark are nested under light and dark keys:

Theme.load({
    primary:      "#7c3aed",
    primaryHover: "#6d28d9",
    primaryActive:"#5b21b6",
    primarySubtle:"#ede9fe",

    light: {
        background:   "#f8fafc",
        panel:        "#f1f5f9",
        surface:      "#ffffff",
        border:       "#e2e8f0",
        textPrimary:  "#0f172a",
        textSecondary:"#475569"
    },
    dark: {
        background:   "#0f172a",
        panel:        "#1e293b",
        surface:      "#1e293b",
        border:       "#334155",
        textPrimary:  "#f8fafc",
        textSecondary:"#94a3b8"
    }
})

Dark mode still works after a load() call — toggling Theme.dark switches between your custom light and dark values, not Mahina's originals.

Loading from a file

Any .json file with the same structure can be loaded at startup:

// main.qml
Component.onCompleted: {
    const xhr = new XMLHttpRequest()
    xhr.open("GET", Qt.resolvedUrl("theme.json"))
    xhr.onreadystatechange = function() {
        if (xhr.readyState === XMLHttpRequest.DONE)
            Theme.load(JSON.parse(xhr.responseText))
    }
    xhr.send()
}

Restoring defaults

Theme.reset() restores every token to the Mahina built-in values. Useful when letting users switch between multiple saved schemas at runtime:

Button { text: "Reset theme"; onClicked: Theme.reset() }

Token reference

Tokens

Every value that appears in a component — colour, size, spacing, radius, duration — comes from a named token on the Theme singleton. Using tokens instead of raw values means a single Theme.load() call repaints the entire UI.

Primary palette

Semantic colors

Surfaces & borders

These tokens have separate light and dark values and switch automatically with Theme.dark.

Text

Spacing

4 px base grid. Use these for margins, paddings and gaps — never raw pixel values.

Border radius

Typefaces

Mahina bundles two fonts as embedded assets — no network requests, no system dependency.

Both tokens are writable and included in Theme.load(), so you can swap to any font the host app registers:

// in main.cpp
QFontDatabase::addApplicationFont(":/fonts/Geist-Variable.ttf");

// in QML
Theme.load({ fontFamily: "Geist", fontFamilyMono: "Fira Code" })

Type scale

Font weights

Animation

Elevation

Three shadow levels for use with Qt's DropShadow layer effect. Each level exposes a blur radius, Y offset, and opacity multiplier paired with Theme.shadowColor.

Components

Example

The repository ships a self-contained kitchen-sink app that renders live instances of the components against a real Qt runtime. It is the fastest way to see how everything looks and behaves together, and to verify that your build environment is set up correctly.

Building

git clone https://github.com/ajunior/mahina.git
cd mahina
cmake -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64
cmake --build build -j$(nproc)
./build/example/bin/MahinaExample

What's inside

A 1000 × 680 window with a NavBar, a Sidebar, and 18 pages that group components by theme. Each page is a scrollable Flickable with live, interactive instances — not screenshots.

Dark mode

Press D at any time to toggle between light and dark. The NavBar also exposes a toggle button. All 262 components respond to the Theme.dark flag with no additional wiring.