👁 Image
Microsoft.Maui.Platforms.Linux.Gtk4.Essentials 0.1.0-preview.11.26317.2

Microsoft.Maui.Platforms.Linux.Gtk4

A .NET MAUI backend for Linux, powered by GTK4. Run your .NET MAUI applications natively on Linux desktops with GTK4 rendering via GirCore bindings.

Status: Early / experimental — contributions and feedback are welcome!

https://github.com/user-attachments/assets/70f2a910-94b3-437c-945a-6b71223c5cd3

Screenshots

<table> <tr> <td><img src="docs/screenshots/home.png" alt="Home" width="400"/><br/><b>Home & Sidebar Navigation</b></td> <td><img src="docs/screenshots/controls.png" alt="Controls" width="400"/><br/><b>Interactive Controls</b></td> </tr> <tr> <td><img src="docs/screenshots/collectionview.png" alt="CollectionView" width="400"/><br/><b>CollectionView (Virtualized)</b></td> <td><img src="docs/screenshots/fontawesome.png" alt="FontAwesome Icons" width="400"/><br/><b>FontAwesome Icons</b></td> </tr> <tr> <td><img src="docs/screenshots/shapes.png" alt="Shapes" width="400"/><br/><b>Shapes & Graphics</b></td> <td><img src="docs/screenshots/layouts.png" alt="Layouts" width="400"/><br/><b>Layouts</b></td> </tr> <tr> <td><img src="docs/screenshots/controltemplate.png" alt="ControlTemplate" width="400"/><br/><b>ControlTemplate & ContentPresenter</b></td> <td><img src="docs/screenshots/pickers.png" alt="Pickers" width="400"/><br/><b>Pickers & Search</b></td> </tr> <tr> <td><img src="docs/screenshots/formattedtext.png" alt="FormattedText" width="400"/><br/><b>FormattedText & Spans</b></td> <td><img src="docs/screenshots/transforms.png" alt="Transforms" width="400"/><br/><b>Transforms & Effects</b></td> </tr> <tr> <td colspan="2"><img src="docs/screenshots/graphics.png" alt="Graphics" width="400"/><br/><b>GraphicsView (Cairo)</b></td> </tr> </table>

Features

Controls and handlers

Layout architecture: StackLayout, Grid, FlexLayout, and AbsoluteLayout all share a single LayoutHandler — the MAUI Layout base class is mapped once, and all concrete layout types resolve through it.

Platform Features

• Native GTK4 rendering — Every control maps to a real GTK4 widget, styled via GTK CSS.
• Blazor Hybrid — Host Blazor components inside a native GTK window via WebKitGTK.
• Gestures — Tap, Pan, Swipe, Pinch, and Pointer gesture recognizers via GTK4 event controllers.
• Animations — TranslateTo, FadeTo, ScaleTo, RotateTo via GtkPlatformTicker + Gsk.Transform at ~60fps.
• Transforms — TranslationX/Y, Rotation, Scale via Gsk.Transform; Shadow (CSS box-shadow), Clip, ZIndex.
• VisualStateManager — Normal, PointerOver, Pressed, Disabled, Focused states via GTK4 event controllers.
• ControlTemplate — Full ContentPresenter and TemplatedView support via IContentView handler mapping.
• Font icons — Embedded font registration with fontconfig/Pango, FontImageSource rendering via Cairo. FontAwesome and custom icon fonts work out of the box.
• FormattedText — Rich text via Pango markup: Span colors, fonts, sizes, bold/italic, underline/strikethrough, character spacing.
• Alerts & Dialogs — DisplayAlert, DisplayActionSheet, DisplayPromptAsync via native GTK4 modal windows.
• Modal Pages — PushModalAsync presents pages as native GTK4 dialog windows by default, with attached properties for custom sizing, content-fit sizing, and inline (legacy) presentation via GtkPage.
• Brushes & Gradients — SolidColorBrush, LinearGradientBrush, RadialGradientBrush via CSS gradients.
• MenuBar — MenuBarItem / MenuFlyoutItem via Gtk.PopoverMenuBar, integrated into Window and NavigationPage handlers via GtkMenuBarManager (not a standalone handler).
• Tooltips & Context Menus — ToolTipProperties.Text and ContextFlyout via Gtk.PopoverMenu.
• Theming — Automatic light/dark theme detection via GtkThemeManager.
• Lifecycle Events — ConfigureLifecycleEvents().AddGtk() hooks for OnWindowCreated and OnMauiApplicationCreated.
• Desktop integration — App icons via hicolor icon theme, .desktop file generation, MauiImage/MauiFont/MauiAsset resource processing.

Essentials (21 of 36 services)

Implementation Parity

Prerequisites

Install GTK4 & WebKitGTK (Debian / Ubuntu)

sudo apt install libgtk-4-dev libwebkitgtk-6.0-dev \
 gobject-introspection libgirepository1.0-dev \
 gir1.2-gtk-4.0 gir1.2-webkit-6.0 pkg-config

Install GTK4 & WebKitGTK (Fedora)

Note: Fedora package names below are unverified. Please open an issue if they need correction.

sudo dnf install gtk4-devel webkitgtk6.0-devel \
 gobject-introspection-devel pkg-config

On Fedora versions where these package names apply, gtk4-devel and webkitgtk6.0-devel typically include the GObject Introspection typelibs, so separate gir1.2-* packages are usually not needed.

Quick Start

Option 1: Use the template (recommended)

# Install the template
dotnet new install Microsoft.Maui.Platforms.Linux.Gtk4.Templates --prerelease

# Create a new Linux MAUI app
dotnet new maui-linux-gtk4 -n MyApp.Linux
cd MyApp.Linux
dotnet run

Option 2: Add to an existing project manually

Add the NuGet package:

dotnet add package Microsoft.Maui.Platforms.Linux.Gtk4 --prerelease
dotnet add package Microsoft.Maui.Platforms.Linux.Gtk4.Essentials --prerelease # optional

Then set up your entry point:

Program.cs

using Microsoft.Maui.Platforms.Linux.Gtk4.Platform;
using Microsoft.Maui.Hosting;

public class Program : GtkMauiApplication
{
 protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();

 public static void Main(string[] args)
 {
 var app = new Program();
 app.Run(args);
 }
}

MauiProgram.cs

using Microsoft.Maui.Platforms.Linux.Gtk4.Hosting;
using Microsoft.Maui.Hosting;

public static class MauiProgram
{
 public static MauiApp CreateMauiApp()
 {
 var builder = MauiApp
 .CreateBuilder()
 .UseMauiAppLinuxGtk4<App>();

 return builder.Build();
 }
}

XAML Support

Microsoft.Maui.Platforms.Linux.Gtk4 relies on MAUI's normal transitive build assets for XAML. In Linux head projects, *.xaml files are still collected as MauiXaml and compiled by MAUI's XAML build pipeline without extra package-specific overrides.

Resource Item Support

Linux head projects can use MAUI resource item groups for common Resources/* paths:

• MauiImage from Resources/Images/**
• MauiFont from Resources/Fonts/**
• MauiAsset from Resources/Raw/** (with LogicalName defaulting to %(RecursiveDir)%(Filename)%(Extension))
• MauiIcon from explicit items, or default Resources/AppIcon/appicon.{svg|png|ico}

These are copied into build/publish output so image/file lookups can resolve at runtime. When MauiIcon is present, Linux builds emit hicolor icon-theme files in output and runtime sets the GTK window default icon name from that icon.

Adding Linux to a Multi-Targeted MAUI App

Since there is no official -linux TFM (Target Framework Moniker) from Microsoft, MAUI projects can't conditionally include the Linux backend via TargetFrameworks the way they do for Android/iOS/Windows. Instead, use the "Linux head project" pattern:

MyApp/ ← Your existing multi-targeted MAUI project
├── MyApp.csproj (net10.0-android;net10.0-ios;...)
├── App.cs
├── MainPage.xaml
├── ViewModels/
├── Services/
└── Platforms/
 ├── Android/
 ├── iOS/
 └── ...

MyApp.Linux/ ← New Linux-specific project
├── MyApp.Linux.csproj (net10.0, references Microsoft.Maui.Platforms.Linux.Gtk4)
├── Program.cs (GtkMauiApplication entry point)
└── MauiProgram.cs (builder.UseMauiAppLinuxGtk4<App>())

Setup

1. Create the Linux head project next to your MAUI project:

dotnet new maui-linux-gtk4 -n MyApp.Linux

2. Reference your shared code — add a project reference from MyApp.Linux.csproj to your MAUI project (or a shared class library):

<ItemGroup>
 <ProjectReference Include="../MyApp/MyApp.csproj" />
</ItemGroup>

3. Run on Linux:

dotnet run --project MyApp.Linux

Why a separate project?

The platform-specific TFMs (net10.0-android, net10.0-ios, etc.) are powered by .NET workloads that Microsoft ships. Creating a custom net10.0-linux TFM would require building and distributing a full .NET workload — complex infrastructure that's unnecessary for most use cases.

The separate project approach works with standard dotnet build/dotnet run, is NuGet-distributable, and keeps your existing MAUI project unchanged.

DevFlow Integration

The GTK4 backend supports for AI-assisted UI inspection, automation, and debugging, including the Blazor CDP bridge. To enable it, set EnableMauiDevFlow=true in Directory.Build.props (or pass it as an MSBuild property):

<PropertyGroup>
 <EnableMauiDevFlow>true</EnableMauiDevFlow>
</PropertyGroup>

When enabled, the sample project (samples/Linux.Gtk4.Sample) conditionally references the DevFlow agent and Blazor projects:

<ItemGroup Condition="'$(EnableMauiDevFlow)' == 'true'">
 <ProjectReference Include="..\..\..\..\src\DevFlow\Microsoft.Maui.DevFlow.Agent.Gtk\Microsoft.Maui.DevFlow.Agent.Gtk.csproj" />
 <ProjectReference Include="..\..\..\..\src\DevFlow\Microsoft.Maui.DevFlow.Blazor.Gtk\Microsoft.Maui.DevFlow.Blazor.Gtk.csproj" />
</ItemGroup>

Building from Source

git clone https://github.com/dotnet/maui-labs.git
cd maui-labs/platforms/Linux.Gtk4
dotnet restore
dotnet build

Run the sample app

# Sample app (includes native controls, Blazor Hybrid, essentials, and more)
dotnet run --project samples/Linux.Gtk4.Sample

Project Structure

Linux.Gtk4.slnx # Platform-local solution file
├── src/
│ ├── Linux.Gtk4/ # Core MAUI backend
│ │ ├── Handlers/ # GTK4 handler implementations
│ │ ├── Hosting/ # AppHostBuilderExtensions (UseMauiAppLinuxGtk4)
│ │ └── Platform/ # GTK application, context, layout, theming
│ ├── Linux.Gtk4.Essentials/ # MAUI Essentials for Linux (clipboard, etc.)
│ └── Linux.Gtk4.BlazorWebView/ # BlazorWebView support via WebKitGTK
├── samples/
│ └── Linux.Gtk4.Sample/ # Sample app (controls, Blazor, essentials)
├── templates/ # dotnet new templates
└── docs/ # Documentation

NuGet Packages

Key Dependencies

License

This project is licensed under the .