Skip to content

Update x:Load attribute documentation #6005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hoshiizumiya wants to merge 3 commits into
base: docs
Choose a base branch
from
Open

Update x:Load attribute documentation #6005

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d693e80
Update x:Load attribute documentation
hoshiizumiya Jun 25, 2026
efc0661
Potential fix for pull request finding
hoshiizumiya Jun 26, 2026
8551a12
clarify
hoshiizumiya Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions hub/apps/develop/platform/xaml/x-load-attribute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ The tracking of deferred elements by the XAML framework adds about 600 bytes to

## XAML attribute usage

> [!CAUTION]
> In the WinUI, [FindName](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.findname) doesn't work when the XAML root element is a `Window`. For details, see [microsoft-ui-xaml #9842](https://github.com/microsoft/microsoft-ui-xaml/issues/9842).

``` syntax
<object x:Load="True" .../>
<object x:Load="False" .../>
Expand All @@ -29,7 +32,7 @@ The tracking of deferred elements by the XAML framework adds about 600 bytes to

There are several different ways to load the elements:

- Use an [x:Bind](x-bind-markup-extension.md) expression to specify the load state. The expression should return **true** to load and **false** to unload the element.
- Use an [x:Bind](x-bind-markup-extension.md) expression to specify the load state. The expression should return **true** to load and **false** to unload the element. If you use `x:Bind` in `x:Load`, don't set `x:Name` to the same identifier as the binding path; otherwise, the XAML compiler reports an error.
- Call [**FindName**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.findname) with the name that you defined on the element.
- Call [**GetTemplateChild**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.gettemplatechild) with the name that you defined on the element.
- In a [**VisualState**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.VisualState), use a [**Setter**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Setter) or **Storyboard** animation that targets the x:Load element.
Expand Down Expand Up @@ -63,10 +66,12 @@ The restrictions for using **x:Load** are:

- You must define an [x:Name](x-name-attribute.md) for the element, as there needs to be a way to find the element later.
- You can only use x:Load on types that derive from [**UIElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.UIElement) or [**FlyoutBase**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.Controls.Primitives.FlyoutBase).
- You cannot use x:Load on root elements in a [**Page**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.page), a [**UserControl**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.usercontrol), or a [**DataTemplate**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.DataTemplate).
- You cannot use x:Load on root elements in a [**Window**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.window), a [**Page**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.page), a [**UserControl**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.usercontrol), or a [**DataTemplate**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.DataTemplate).
- You cannot use x:Load on elements in a [**ResourceDictionary**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.ResourceDictionary).
- You cannot use x:Load on loose XAML loaded with [**XamlReader.Load**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.markup.xamlreader.load).
- Moving a parent element will clear out any elements that have not been loaded.
- In C++/WinRT, using `x:Load` with `x:Bind` can produce a compile error. For details and a workaround, see [microsoft-ui-xaml #7579](https://github.com/microsoft/microsoft-ui-xaml/issues/7579).
- In C++/WinRT, `FindName` doesn't reload an object that was previously unloaded using `UnloadObject`. For details, see [microsoft-ui-xaml #10179](https://github.com/microsoft/microsoft-ui-xaml/issues/10179).

## Remarks

Expand Down