MahApps/MahApps.Metro · error · Exception

OptionsListView is not defined yet. Please use OptionsItemsS

Error message

OptionsListView is not defined yet. Please use OptionsItemsSource instead.

What it means

Thrown by the HamburgerMenu.OptionsItems getter when optionsListView is null. The OptionsListView is a template part resolved in OnApplyTemplate via GetTemplateChild("OptionsListView"); it is null when the control's ControlTemplate does not define that part, or when OptionsItems is accessed before the template is applied. The message directs users to OptionsItemsSource, which works without the template part.

Source

Thrown at src/MahApps.Metro/Controls/HamburgerMenu/HamburgerMenu.Options.cs:171

        public object? OptionsItemCommandParameter
        {
            get => this.GetValue(OptionsItemCommandParameterProperty);
            set => this.SetValue(OptionsItemCommandParameterProperty, value);
        }

        /// <summary>
        /// Gets the collection used to generate the content of the option list.
        /// </summary>
        /// <exception cref="Exception">
        /// Exception thrown if OptionsListView is not yet defined.
        /// </exception>
        public ItemCollection OptionsItems
        {
            get
            {
                if (this.optionsListView is null)
                {
                    throw new Exception("OptionsListView is not defined yet. Please use OptionsItemsSource instead.");
                }

                return this.optionsListView.Items;
            }
        }

        /// <summary>
        /// Executes the <see cref="OptionsItemCommand"/>.
        /// </summary>
        public void RaiseOptionsItemCommand()
        {
            var command = this.OptionsItemCommand;
            var commandParameter = this.OptionsItemCommandParameter ?? this;
            if (command != null && command.CanExecute(commandParameter))
            {
                command.Execute(commandParameter);
            }
        }

View on GitHub (pinned to 72099e310b)

Solutions

  1. Use the OptionsItemsSource property (bound in XAML) instead of the OptionsItems collection, as it does not require the template part.
  2. Ensure the HamburgerMenu ControlTemplate includes a ListBox named 'OptionsListView'.
  3. Access OptionsItems only after the control's Loaded event (OnApplyTemplate has run).
  4. Null-check or use the default HamburgerMenu template.

Example fix

<!-- before: reading the collection in code too early / missing template -->
<controls:HamburgerMenu x:Name="Menu" />  // menu.OptionsItems accessed in ctor -> throws

<!-- after: bind via ItemsSource instead -->
<controls:HamburgerMenu OptionsItemsSource="{Binding OptionCommands}" />
Defensive patterns

Strategy: validation

Validate before calling

// Prefer binding via ItemsSource; only touch the collection after Loaded.
if (menu.IsLoaded)
{
    var items = menu.OptionsItems; // safe after template applied
}
// In XAML, bind instead: OptionsItemsSource="{Binding ...}"

Type guard

static bool HasOptionsListView(HamburgerMenu m)
    => m.IsLoaded && m.Template.FindName("OptionsListView", m) is ListBox;

Try / catch

try { var items = menu.OptionsItems; }
catch (Exception ex) when (ex.Message.Contains("OptionsListView is not defined"))
{
    // Template missing the part; switch to OptionsItemsSource binding.
}

Prevention

When it happens

Trigger: Using a custom HamburgerMenu ControlTemplate that omits the 'OptionsListView' ListBox; reading OptionsItems during construction before OnApplyTemplate runs; accessing OptionsItems in XAML code-behind before the control Loaded.

Common situations: Custom hamburger template for a sidebar without the options region; accessing OptionsItems in a constructor or InitializeComponent path; design-time access.

Related errors

AI-assisted analysis of MahApps/MahApps.Metro@72099e310b (2026-08-13). Data as JSON: /api/errors/c446897e8a550339. Report an issue: GitHub.