Avalonia.Samples: one Avalonia feature per folder, tagged by how much you should already know

One topic per subfolder, and no sample depends on another

Avalonia.Samples collects minimal samples that make it easy to get started with Avalonia, and the guiding rule is that each one focuses on a single aspect. The repository states it directly: every sample can be found in its own subfolder and can run without any reference to another sample. That is a stronger guarantee than a demo project usually offers, and it is the one that matters when you are learning, because it means you can open one folder, understand the whole thing, and delete it afterwards. Alongside that there is a `*.slnx` file holding every project in one solution for people who want the complete collection. The README notes that the project has migrated to the newer `*.slnx` file format, which should be supported by all major IDEs, and that if it does not work for you, the individual project files inside the subdirectories are the fallback. Every sample folder also contains its own `README` file describing the sample in detail, with links to further information where that applies.

A four level difficulty ladder replaces a vague ordering

The indexing idea is what separates this from a pile of demo apps. Each sample is tagged with a difficulty, and the README defines what each level means in terms of how much base knowledge a user should have. Beginner means no knowledge of Avalonia at all, though basic knowledge of `C#`, `X(A)ML` and your IDE is mandatory. Easy means some very basic knowledge of Avalonia is needed. Normal means the user is somewhat experienced with Avalonia. Hard covers samples focused on non-standard tasks that most users will not need to know. That fourth level is the honest one, and it is where the repository admits that some samples exist to demonstrate a technique rather than to be part of a learning path. Alongside the difficulty, every sample carries buzz words, which the README says are there for better search results. So the catalogue answers two questions at once: what do you need to know already, and what words would you have searched for.

The catalogue covers MVVM, drawing, data templates and custom controls

The sample list is organised into categories, and reading it tells you what the project considers the core of Avalonia. The MVVM section has four entries: a Basic MVVM Sample tagged with ReactiveUI, INotifyPropertyChanged, XAML and Binding; a Commands Sample covering ICommand, CommandParameter, ReactiveCommand and async-await; a ValueConverter Sample with Converter, MultiBinding, IValueConverter and FuncValueConverter; and a Validation Sample with Data-Validation, Error and Error-Message. DesktopIntegration has a single Tray Icon Sample. Drawing holds the BattleCity Game Sample, tagged Game, Canvas, Game Loop and MVVM, and a Rect Painter Sample for Graphics. DataTemplates has Basic, Func and IDataTemplate variants, the last one also covering DataTemplateSelector. Custom Controls offers a RatingControl Sample covering TemplatedControl, AvaloniaProperty, StyledProperty, DirectProperty and ControlTheme, plus a SnowflakesControl Sample on Render, Hit-Testing and Custom Animations. Routing has a Basic ViewLocator Sample. View Interaction covers an MVVM Dialog Sample and a Dialog Manager Sample, both touching FileDialogs, TopLevel and Clipboard. The set is broad rather than deep, and the pattern is consistent: a real feature, a small application.

Three ways to test a UI, at two very different costs

The Automated UI Testing section is the most opinionated part of the catalogue, and it shows the clearest difference in approach inside one repository. Two entries are headless: Testing with Headless XUnit and Testing with Headless NUnit, both tagged Automation and UI Testing and rated Normal. The third, Testing with Appium, is rated Hard and brings in Appium and WinAppDriver. The distinction that matters is the machine you need. A headless test drives the Avalonia UI in process, so it runs in the same test run as your unit tests and needs no extra driver stack. The Appium route drives a real running application through an external automation server, which is the only way to test something the process cannot host, and it is also the path that depends on WinAppDriver, a Windows component. The difficulty tags encode that cost difference honestly, and the three samples together are a usable decision: pick the headless one unless your test genuinely has to observe a deployed application.

The README is AsciiDoc, which changes how you read and edit it

The documentation file is `README.adoc`, and the source shows it plainly: it is written in AsciiDoc with a table of contents, conditional blocks for the GitHub rendering environment, and cross-references between sections. The repository also contains `index.html`, a `_docs/` directory, a `scripts/` directory and a `nuget.config` at the top level, and a `.nojekyll` file, which is the marker GitHub Pages uses to serve a directory as static files without running it through Jekyll. The published result is the documentation site at avaloniaui.github.io/Avalonia.Samples. Two consequences follow for a contributor. The sample tables in the document are generated from a template block that tells you to copy it for a new entry and replace the placeholder text, so adding a sample means editing the AsciiDoc table as well as adding the folder. And the notation used for links, images and admonitions is AsciiDoc specific, so a pull request that pastes Markdown into `README.adoc` will not render. The README also asks people to use GitHub Discussions for questions, a Telegram chat for quick contact, and the issues section for bug reports and feature requests.

What the samples deliberately leave out

Two limitations are structural rather than accidental. The first is that these are teaching artifacts. A sample tagged with buzz words such as MVVM, Binding or DataTemplate exists to make one mechanism visible, so it will not include the error handling, logging, localisation, theming and packaging that a production application needs, and copying one wholesale into a product is a mistake. The second is that the repository is a moving target. There are no GitHub releases, so nothing pins the Avalonia version a given sample was written against, and the samples sit on the main branch and change as the framework moves. The last push was on 2026-10-14, which says the samples are being kept current, but it also means the specific code you read today may differ from the code in the tutorial you followed last month. If you need a stable reference for a training course or a book, copying the relevant sample into your own repository at a known commit is the safer move than linking to the live folder.

A closer alternative for a single feature, and a closer one for tests

Two comparisons are worth making, and they point in opposite directions. For learning a specific feature, the alternative to the sample catalogue is the framework's own documentation. The difference is that documentation explains a mechanism, while a sample shows you a small application that produces a result, with the XAML, the view model and the project file together. You can read the documentation in thirty seconds; you can only learn the wiring from the sample. For testing, the alternative to the headless samples is driving the application externally, which is exactly what the Appium sample does, but the samples make the cost visible: headless stays inside your test run, Appium needs a driver and, through WinAppDriver, a Windows host. Neither alternative is a different tool so much as a different point on the same axis, and this repository is unusual in labelling both ends of it.

Editorial conclusion

Adopt Avalonia.Samples as a reference shelf when you are learning Avalonia or when a specific control or pattern has no obvious example in the official documentation. Do not adopt it as a production code base, since every sample is deliberately minimal, independent of the others, and written to demonstrate one thing rather than to be extended. Before you copy from it, check the difficulty tag against your own baseline, since a Beginner sample still assumes C#, X(A)ML and an IDE, and confirm the sample you want sits in a category the repository actually covers. The licence is MIT, the last push was on 2026-10-14, and the repository publishes no GitHub releases, so the samples track the main branch rather than a versioned package.

Frequently asked questions

Official sources

1. AvaloniaUI/Avalonia.Samples on GitHub
2. Issues
3. License: MIT
4. Project website
5. README