## 1. Project Overview & Quickstart (AvaloniaUI/Avalonia) ## File: README.md [](https://github.com/sponsors/AvaloniaUI) [](https://avaloniaui.net?utm_source=github&utm_medium=referral&utm_content=readme_link) [](https://dev.azure.com/AvaloniaUI/AvaloniaUI/_build/latest?definitionId=4) [](https://www.nuget.org/packages/Avalonia) [](https://www.nuget.org/packages/Avalonia) ## 📖 About [Avalonia](https://avaloniaui.net?utm_source=github&utm_medium=referral&utm_content=readme_link) is a cross-platform UI framework for dotnet, providing a flexible styling system and supporting a wide range of platforms such as Windows, macOS, Linux, iOS, Android and WebAssembly. Avalonia is mature and production ready and is used by companies, including [Schneider Electric](https://avaloniaui.net/showcase#se), [Unity](https://avaloniaui.net/showcase#unity), [JetBrains](https://avaloniaui.net/showcase#rider) and [GitHub](https://avaloniaui.net/showcase#github). Considered by many to be the spiritual successor to WPF, Avalonia UI provides a familiar, modern development experience for XAML developers creating cross-platform applications. While Avalonia UI is [similar to WPF](https://docs.avaloniaui.net/docs/next/get-started/wpf/), it isn't a 1:1 copy, and you'll find plenty of improvements. For those seeking a cross-platform WPF, we have created [Avalonia XPF](https://avaloniaui.net/xpf?utm_source=github&utm_medium=referral&utm_content=readme_link), enabling WPF applications to run on macOS and Linux with little to no code changes. Avalonia XPF is a commercial product and is licensed per-app, per-platform. ### Blog To see the latest announcements and read about the state of Avalonia, check out the [Avalonia UI Blog](https://www.avaloniaui.net/blog?utm_source=github&utm_medium=referral&utm_content=readme_link). ### Sponsorship Avalonia development is supported by the generous sponsorship of [Devolutions](https://devolutions.net/?utm_source=pr&utm_medium=partnership&utm_campaign=avalonia&utm_id=C086&member_status=responded). --- ## 🚀 Getting Started See our [Get Started](https://docs.avaloniaui.net/docs/get-started?utm_source=github&utm_medium=referral&utm_content=readme_link) guide to begin developing apps with Avalonia UI. ### Visual Studio Code The [Avalonia for Code](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.vscode-avalonia) extension gives you everything you need to build cross-platform .NET apps. XAML previewing, code completion, diagnostics, and code navigation, all inside the world's most popular editor. It's the fastest way to get started with Avalonia. ### Visual Studio 2022 & 2026 The Avalonia [Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.AvaloniaVS) contains project and control templates, a live XAML previewer, code completion, and full diagnostics directly into Visual Studio. ### JetBrains Rider [JetBrains Rider](https://www.jetbrains.com/rider/whatsnew/?mkt_tok=eyJpIjoiTURBNU1HSmhNV0kwTUdFMiIsInQiOiJtNnU2VEc1TlNLa1ZRVkROYmdZYVpYREJsaU1qdUhmS3dxSzRHczdYWHl0RVlTNDMwSFwvNUs3VENTNVM0bVcyNFdaRmVYZzVWTTF1N3VrQWNGTkJreEhlam1hMlB4UVVWcHBGM1dNOUxoXC95YnRQdGgyUXl1YmZCM3h3d3BVWWdBIn0%3D#avalonia-support) supports for Avalonia. Code completion, inspections and refactorings are supported out of the box. To enable previewing XAML, you will require a 3rd party, community-maintained extension: `https://plugins.jetbrains.com/plugins/dev/14839` to plugin repositories and install [AvaloniaRider](https://github.com/ForNeVeR/AvaloniaRider) plugin. ### Avalonia Packages Avalonia is delivered via **NuGet** package manager. You can find the packages here: https://www.nuget.org/packages/Avalonia/ Use these commands in the Package Manager console to install Avalonia manually: ``` Install-Package Avalonia Install-Package Avalonia.Desktop ``` --- ## Bleeding Edge Builds We also have a [nightly build](https://github.com/AvaloniaUI/Avalonia/wiki/Using-nightly-build-feed) which tracks the current state of master. Although these packages are less stable than the release on NuGet.org, you'll get all the latest features and bugfixes right away and many of our users actually prefer this feed! --- ## Learning ### Documentation Documentation can be found at https://docs.avaloniaui.net. ### Tutorials We also have a [tutorial](https://docs.avaloniaui.net/docs/get-started/starter-tutorial) over there for newcomers. ### Samples We have a [range of samples](https://github.com/AvaloniaUI/Avalonia.Samples) to help you get started. ### Breaking Changes You can also see what [breaking changes](https://docs.avaloniaui.net/docs/avalonia12-breaking-changes) between Avalonia 11 and Avalonia 12. --- ## Building and Using See the [build instructions here](docs/build.md). --- ## Contributing This project exists thanks to all the people who contribute. Please read the [contribution guidelines](CONTRIBUTING.md) before submitting a pull request. ### Code of Conduct This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the [Code of Conduct](CODE_OF_CONDUCT.md). --- ## Security If you discover a security vulnerability in any of our SDKs, tools, services, or repositories, please help us keep the community safe by reporting it responsibly. You can report security vulnerabilities by emailing **[security@avaloniaui.net](mailto:security@avaloniaui.net)**. Please avoid disclosing the issue publicly until we have had a reasonable amount of time to investigate and release a patch or mitigation. We review all legitimate reports and will work with you to quickly resolve the issue. Please note that Avalonia does not operate a bug bounty programme. --- ## Licence Avalonia is licenced under the [MIT licence](licence.md). ## XPF - cross-platform WPF Unleash the full potential of your existing WPF apps with our cross-platform UI framework, enabling WPF apps to run on macOS and Linux without requiring expensive and risky rewrites. [](https://avaloniaui.net/xpf?utm_source=github&utm_medium=referral&utm_content=readme_ad) --- ## File: Readme.md [](https://github.com/sponsors/AvaloniaUI) [](https://avaloniaui.net?utm_source=github&utm_medium=referral&utm_content=readme_link) [](https://dev.azure.com/AvaloniaUI/AvaloniaUI/_build/latest?definitionId=4) [](https://www.nuget.org/packages/Avalonia) [](https://www.nuget.org/packages/Avalonia) ## 📖 About [Avalonia](https://avaloniaui.net?utm_source=github&utm_medium=referral&utm_content=readme_link) is a cross-platform UI framework for dotnet, providing a flexible styling system and supporting a wide range of platforms such as Windows, macOS, Linux, iOS, Android and WebAssembly. Avalonia is mature and production ready and is used by companies, including [Schneider Electric](https://avaloniaui.net/showcase#se), [Unity](https://avaloniaui.net/showcase#unity), [JetBrains](https://avaloniaui.net/showcase#rider) and [GitHub](https://avaloniaui.net/showcase#github). Considered by many to be the spiritual successor to WPF, Avalonia UI provides a familiar, modern development experience for XAML developers creating cross-platform applications. While Avalonia UI is [similar to WPF](https://docs.avaloniaui.net/docs/next/get-started/wpf/), it isn't a 1:1 copy, and you'll find plenty of improvements. For those seeking a cross-platform WPF, we have created [Avalonia XPF](https://avaloniaui.net/xpf?utm_source=github&utm_medium=referral&utm_content=readme_link), enabling WPF applications to run on macOS and Linux with little to no code changes. Avalonia XPF is a commercial product and is licensed per-app, per-platform. ### Blog To see the latest announcements and read about the state of Avalonia, check out the [Avalonia UI Blog](https://www.avaloniaui.net/blog?utm_source=github&utm_medium=referral&utm_content=readme_link). ### Sponsorship Avalonia development is supported by the generous sponsorship of [Devolutions](https://devolutions.net/?utm_source=pr&utm_medium=partnership&utm_campaign=avalonia&utm_id=C086&member_status=responded). --- ## 🚀 Getting Started See our [Get Started](https://docs.avaloniaui.net/docs/get-started?utm_source=github&utm_medium=referral&utm_content=readme_link) guide to begin developing apps with Avalonia UI. ### Visual Studio Code The [Avalonia for Code](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.vscode-avalonia) extension gives you everything you need to build cross-platform .NET apps. XAML previewing, code completion, diagnostics, and code navigation, all inside the world's most popular editor. It's the fastest way to get started with Avalonia. ### Visual Studio 2022 & 2026 The Avalonia [Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.AvaloniaVS) contains project and control templates, a live XAML previewer, code completion, and full diagnostics directly into Visual Studio. ### JetBrains Rider [JetBrains Rider](https://www.jetbrains.com/rider/whatsnew/?mkt_tok=eyJpIjoiTURBNU1HSmhNV0kwTUdFMiIsInQiOiJtNnU2VEc1TlNLa1ZRVkROYmdZYVpYREJsaU1qdUhmS3dxSzRHczdYWHl0RVlTNDMwSFwvNUs3VENTNVM0bVcyNFdaRmVYZzVWTTF1N3VrQWNGTkJreEhlam1hMlB4UVVWcHBGM1dNOUxoXC95YnRQdGgyUXl1YmZCM3h3d3BVWWdBIn0%3D#avalonia-support) supports for Avalonia. Code completion, inspections and refactorings are supported out of the box. To enable previewing XAML, you will require a 3rd party, community-maintained extension: `https://plugins.jetbrains.com/plugins/dev/14839` to plugin repositories and install [AvaloniaRider](https://github.com/ForNeVeR/AvaloniaRider) plugin. ### Avalonia Packages Avalonia is delivered via **NuGet** package manager. You can find the packages here: https://www.nuget.org/packages/Avalonia/ Use these commands in the Package Manager console to install Avalonia manually: ``` Install-Package Avalonia Install-Package Avalonia.Desktop ``` --- ## Bleeding Edge Builds We also have a [nightly build](https://github.com/AvaloniaUI/Avalonia/wiki/Using-nightly-build-feed) which tracks the current state of master. Although these packages are less stable than the release on NuGet.org, you'll get all the latest features and bugfixes right away and many of our users actually prefer this feed! --- ## Learning ### Documentation Documentation can be found at https://docs.avaloniaui.net. ### Tutorials We also have a [tutorial](https://docs.avaloniaui.net/docs/get-started/starter-tutorial) over there for newcomers. ### Samples We have a [range of samples](https://github.com/AvaloniaUI/Avalonia.Samples) to help you get started. ### Breaking Changes You can also see what [breaking changes](https://docs.avaloniaui.net/docs/avalonia12-breaking-changes) between Avalonia 11 and Avalonia 12. --- ## Building and Using See the [build instructions here](docs/build.md). --- ## Contributing This project exists thanks to all the people who contribute. Please read the [contribution guidelines](CONTRIBUTING.md) before submitting a pull request. ### Code of Conduct This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the [Code of Conduct](CODE_OF_CONDUCT.md). --- ## Security If you discover a security vulnerability in any of our SDKs, tools, services, or repositories, please help us keep the community safe by reporting it responsibly. You can report security vulnerabilities by emailing **[security@avaloniaui.net](mailto:security@avaloniaui.net)**. Please avoid disclosing the issue publicly until we have had a reasonable amount of time to investigate and release a patch or mitigation. We review all legitimate reports and will work with you to quickly resolve the issue. Please note that Avalonia does not operate a bug bounty programme. --- ## Licence Avalonia is licenced under the [MIT licence](licence.md). ## XPF - cross-platform WPF Unleash the full potential of your existing WPF apps with our cross-platform UI framework, enabling WPF apps to run on macOS and Linux without requiring expensive and risky rewrites. [](https://avaloniaui.net/xpf?utm_source=github&utm_medium=referral&utm_content=readme_ad) --- ## File: readme.md [](https://github.com/sponsors/AvaloniaUI) [](https://avaloniaui.net?utm_source=github&utm_medium=referral&utm_content=readme_link) [](https://dev.azure.com/AvaloniaUI/AvaloniaUI/_build/latest?definitionId=4) [](https://www.nuget.org/packages/Avalonia) [](https://www.nuget.org/packages/Avalonia) ## 📖 About [Avalonia](https://avaloniaui.net?utm_source=github&utm_medium=referral&utm_content=readme_link) is a cross-platform UI framework for dotnet, providing a flexible styling system and supporting a wide range of platforms such as Windows, macOS, Linux, iOS, Android and WebAssembly. Avalonia is mature and production ready and is used by companies, including [Schneider Electric](https://avaloniaui.net/showcase#se), [Unity](https://avaloniaui.net/showcase#unity), [JetBrains](https://avaloniaui.net/showcase#rider) and [GitHub](https://avaloniaui.net/showcase#github). Considered by many to be the spiritual successor to WPF, Avalonia UI provides a familiar, modern development experience for XAML developers creating cross-platform applications. While Avalonia UI is [similar to WPF](https://docs.avaloniaui.net/docs/next/get-started/wpf/), it isn't a 1:1 copy, and you'll find plenty of improvements. For those seeking a cross-platform WPF, we have created [Avalonia XPF](https://avaloniaui.net/xpf?utm_source=github&utm_medium=referral&utm_content=readme_link), enabling WPF applications to run on macOS and Linux with little to no code changes. Avalonia XPF is a commercial product and is licensed per-app, per-platform. ### Blog To see the latest announcements and read about the state of Avalonia, check out the [Avalonia UI Blog](https://www.avaloniaui.net/blog?utm_source=github&utm_medium=referral&utm_content=readme_link). ### Sponsorship Avalonia development is supported by the generous sponsorship of [Devolutions](https://devolutions.net/?utm_source=pr&utm_medium=partnership&utm_campaign=avalonia&utm_id=C086&member_status=responded). --- ## 🚀 Getting Started See our [Get Started](https://docs.avaloniaui.net/docs/get-started?utm_source=github&utm_medium=referral&utm_content=readme_link) guide to begin developing apps with Avalonia UI. ### Visual Studio Code The [Avalonia for Code](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.vscode-avalonia) extension gives you everything you need to build cross-platform .NET apps. XAML previewing, code completion, diagnostics, and code navigation, all inside the world's most popular editor. It's the fastest way to get started with Avalonia. ### Visual Studio 2022 & 2026 The Avalonia [Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.AvaloniaVS) contains project and control templates, a live XAML previewer, code completion, and full diagnostics directly into Visual Studio. ### JetBrains Rider [JetBrains Rider](https://www.jetbrains.com/rider/whatsnew/?mkt_tok=eyJpIjoiTURBNU1HSmhNV0kwTUdFMiIsInQiOiJtNnU2VEc1TlNLa1ZRVkROYmdZYVpYREJsaU1qdUhmS3dxSzRHczdYWHl0RVlTNDMwSFwvNUs3VENTNVM0bVcyNFdaRmVYZzVWTTF1N3VrQWNGTkJreEhlam1hMlB4UVVWcHBGM1dNOUxoXC95YnRQdGgyUXl1YmZCM3h3d3BVWWdBIn0%3D#avalonia-support) supports for Avalonia. Code completion, inspections and refactorings are supported out of the box. To enable previewing XAML, you will require a 3rd party, community-maintained extension: `https://plugins.jetbrains.com/plugins/dev/14839` to plugin repositories and install [AvaloniaRider](https://github.com/ForNeVeR/AvaloniaRider) plugin. ### Avalonia Packages Avalonia is delivered via **NuGet** package manager. You can find the packages here: https://www.nuget.org/packages/Avalonia/ Use these commands in the Package Manager console to install Avalonia manually: ``` Install-Package Avalonia Install-Package Avalonia.Desktop ``` --- ## Bleeding Edge Builds We also have a [nightly build](https://github.com/AvaloniaUI/Avalonia/wiki/Using-nightly-build-feed) which tracks the current state of master. Although these packages are less stable than the release on NuGet.org, you'll get all the latest features and bugfixes right away and many of our users actually prefer this feed! --- ## Learning ### Documentation Documentation can be found at https://docs.avaloniaui.net. ### Tutorials We also have a [tutorial](https://docs.avaloniaui.net/docs/get-started/starter-tutorial) over there for newcomers. ### Samples We have a [range of samples](https://github.com/AvaloniaUI/Avalonia.Samples) to help you get started. ### Breaking Changes You can also see what [breaking changes](https://docs.avaloniaui.net/docs/avalonia12-breaking-changes) between Avalonia 11 and Avalonia 12. --- ## Building and Using See the [build instructions here](docs/build.md). --- ## Contributing This project exists thanks to all the people who contribute. Please read the [contribution guidelines](CONTRIBUTING.md) before submitting a pull request. ### Code of Conduct This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the [Code of Conduct](CODE_OF_CONDUCT.md). --- ## Security If you discover a security vulnerability in any of our SDKs, tools, services, or repositories, please help us keep the community safe by reporting it responsibly. You can report security vulnerabilities by emailing **[security@avaloniaui.net](mailto:security@avaloniaui.net)**. Please avoid disclosing the issue publicly until we have had a reasonable amount of time to investigate and release a patch or mitigation. We review all legitimate reports and will work with you to quickly resolve the issue. Please note that Avalonia does not operate a bug bounty programme. --- ## Licence Avalonia is licenced under the [MIT licence](licence.md). ## XPF - cross-platform WPF Unleash the full potential of your existing WPF apps with our cross-platform UI framework, enabling WPF apps to run on macOS and Linux without requiring expensive and risky rewrites. [](https://avaloniaui.net/xpf?utm_source=github&utm_medium=referral&utm_content=readme_ad) --- ## File: docs/index.md # Avalonia Developer Documentation This documentation covers Avalonia framework development. For user documentation on how to use Avalonia, visit https://docs.avaloniaui.net/. ## Getting Started - [Building Avalonia](build.md) describes how to build Avalonia from source - You should read the [Contributing guidelines](../CONTRIBUTING.md) before you start - We have a [Code of Conduct](../CODE_OF_CONDUCT.md) ## Development - [Debugging the XAML Compiler](debug-xaml-compiler.md) - [Porting Code from 3rd Party Sources](porting-code-from-3rd-party-sources.md) - [Building Local NuGet Packages](nuget.md) ## Releases - [API Compatibility](api-compat.md) describes the API compatibility guarantees provided by Avalonia, and exceptions to these guarantees - Our [Release Process](release.md) describes the process for creating a new Avalonia release ## 2. Official Technical Reference & Guides (AvaloniaUI/Avalonia-docs) The repository holds the code and markdown source files for the Avalonia UI documentation website, which is accessible at [docs.avaloniaui.net](https://docs.avaloniaui.net) ## Index - [Index](#index) - [Feedback](#feedback) - [Documentation Issues](#documentation-issues) - [Contributing](#contributing) - [Workflow](#workflow) - [Conventions](#conventions) - [Local setup](#local-setup) - [Requirements](#requirements) - [Setup](#setup) - [Starting](#starting) - [Thanks 💜](#thanks-) ## Feedback We welcome your valuable feedback on the documentation! Please feel free to join our [Community on Telegram](https://t.me/Avalonia) and send us a message. We would be delighted to hear from you and assist you with any queries or concerns you may have. ## Documentation Issues If you come across any issues with the documentation or have a feature request related explicitly to it, we encourage you to create a new [GitHub issue](https://github.com/AvaloniaUI/avalonia-docs/issues/new). Before creating a new issue, we kindly request that you check for existing issues to avoid duplication. ## Contributing To contribute to Avalonia UI documentation, you need to fork this repository and submit a pull request for the Markdown and/or image changes that you're proposing. ### Workflow The two suggested workflows are: - For small changes, use the "Edit this page" button on each page to edit the Markdown file directly on GitHub. - If you plan to make significant changes or preview the changes locally, clone the repo to your system to and follow the installation and local development steps in [Local setup](#local-setup). ### Conventions - The front matter for every markdown file should include the `id` and a `title`. `id` will be used to reference the file in `sidebar.js` or `version-x.x.x-sidebars.json` for a specific version. ```yaml --- id: platform-support title: Supported Platforms --- ``` - Use `kebab-case` for file and folder names. For example: - `/docs/getting-started/ide-extensions.md` - `/docs/how-to/use-google-fonts.md` - Images are important to bring the product to life and clarify the written content. For images you're adding to the repo, store them in the `img` subfolder inside `static` folder. For every topic there needs to be a folder inside `\static\img\` section, for example: `static\img\how-to\use-google-fonts\download-font.png`. When you link to an image, the path and filename are case-sensitive. The convention is `kebab-case`. `import` should be used to help detect broken images and placed near the top of the document for easier maintenance. > Example code for adding an image in markdown file: ```markdown import ButtonGroup from '/img/button-group.png'; ``` Do not include quotes around the `src`'s attribute value. ## Local setup ### Requirements - **Node version >= 18** ### Setup ```bash npm install ``` ### Starting ```bash npx docusaurus start npx docusaurus start --locale zh-Hans npx docusaurus start --locale ru ``` ### API Reference Generation The API reference pages are generated using the `dotnet-apiref` tool and the configuration in `apiref.json`. The generated output is committed to the repository, so CI and other contributors do not need the tool installed to build the site. #### Running manually To regenerate API reference content locally, install the `dotnet-apiref` tool and run: ```bash npm run apiref:materialise ``` This runs `dotnet-apiref materialise --site .`, which reads `apiref.json`, fetches NuGet packages, and writes API documentation files into the site. #### Automatic regeneration (optional) If you want API reference content to regenerate automatically before every local `build` or `start`, add these lifecycle hooks to the `scripts` section of `package.json`: ```json "prestart": "npm run apiref:materialise", "prebuild": "npm run apiref:materialise" ``` Do not commit these hooks, as CI does not have `dotnet-apiref` installed and the build will fail. The generated API reference files are already committed to the repository. ## Thanks 💜 Thanks for all your contributions and efforts towards improving the Avalonia UI documentation. We thank you being part of our ✨ community ✨!