Pivot.SelectedIndex set to -1 throws COMException, conflicting with official documentation example

[Scighost]

Describe the bug

In the documentation for the Pivot control, there is an example that decrements SelectedIndex to navigate to the previous item:

private void BackButton_Click(object sender, RoutedEventArgs e)
{
    if (rootPivot.SelectedIndex > 0)
    {
        // If not at the first item, go back to the previous one.
        rootPivot.SelectedIndex -= 1;
    }
    else
    {
        // The first PivotItem is selected, so loop around to the last item.
        rootPivot.SelectedIndex = rootPivot.Items.Count-1;
    }
}

However, in actual usage, when this operation results in SelectedIndex being set to -1, a COMException is always thrown at runtime.

Why is this important?

This behavior directly contradicts the official documentation and can easily mislead developers.

Steps to reproduce the bug

1. Create a new WinUI 3 project.
2. Add the following code:

<Grid>
    <Pivot x:Name="pivot">
        <PivotItem Header="1" />
        <PivotItem Header="2" />
        <PivotItem Header="3" />
    </Pivot>
    <Button Click="Button_Click" Content="Click" />
</Grid>

private void Button_Click(object sender, RoutedEventArgs e)
{
    if (pivot.SelectedIndex > 0)
    {
        pivot.SelectedIndex = -1;
    }
    else
    {
        pivot.SelectedIndex++;
    }
}

3. Run and click the button.

Actual behavior

A COMException is thrown when SelectedIndex becomes -1.

Expected behavior

• Setting SelectedIndex to -1 should be handled gracefully (for example, clamped to 0 or ignored).

OR

• The documentation example should clearly state that SelectedIndex must be validated and must not be set to -1, and provide a corrected sample implementation.

Screenshots

NuGet package version

WinUI 3 - Windows App SDK 1.8.3: 1.8.251106002

Windows version

Windows 11 (24H2): Build 26100

Additional context

No response

[riverar]

I think you misread the documentation. Note it has -= not =-.

[Scighost]

Thank you for your answer, I didn't see it clearly. 😂