Skip to documentation content

Menu Item

On this page

    The menu item object and its properties.

    {{ menu_item }}

    Properties
    Name Type Description
    object_type string Will always be menu_item
    is_valid boolean True if this references a published menu_item
    guid string The unique identifier for this menu_item
    value string Contains the same value as guid
    menu_guid string The unique identifier of the related menu
    menu {{ menu }} Reference to the related menu object
    parent_menu_item_guid string The unique identifier of the parent menu_item, if applicable
    parent_menu_item {{ menu_item }} Reference to the parent menu_item object, if applicable
    name {{ text }} The lable used to display this menu_item in the navigation menu
    href {{ url }} Destination URL to navigate to when clicked
    open_in_new_tab boolean If true, the link should open in a new browser tab/window
    description {{ textarea }} Short descriptive text to display with this menu_item
    content {{ html }} HTML content to display with this menu_item
    image_guid string The unique identifier of the related image
    image {{ image }} Reference to the related image object
    depth integer Hierarchy depth of this item within its parent structure, where top-level menu items have a depth of 1, their children have a depth of 2, and so on
    order integer Display order of this item relative to its siblings
    items {{ menu_items }} A list containing all of the menu items that are direct children of the current menu item
    field_id string The identifier for this field
    label string The label for this field
    output string The default output that the menu_item produces when output directly to the template. The default output may change at any time. Template developers should avoid using this and should handle the output of menu items themselves
    Example Load one menu_item and show its href and child items{% menu_item %} loads a single menu item by name or GUID; href, depth, and items describe the link and its children.
    Liquid
    {%- menu_item var link = "Products" -%}
{%- if link.is_valid -%}
	<a href="{{ link.href }}"{% if link.open_in_new_tab %} target="_blank"{% endif %}>{{ link.name }}</a>
	{%- if link.items.size > 0 -%}
		<ul>
		{%- for child in link.items -%}
			<li><a href="{{ child.href }}">{{ child.name }}</a></li>
		{%- endfor -%}
		</ul>
	{%- endif -%}
{%- endif -%}

    {% menu_item %} fetches a single menu item. Pass a name or GUID after the assignment target. Item-specific fields include href, open_in_new_tab, depth, order, items (child menu_items), and menu (the parent menu).

    Example Combine the items of two menus into one list{% menu_items %} builds a list from what you give prepend and append; it never fetches, so pass it the items you want.
    Liquid
    {%- menu var main = "Main Menu" -%}
{%- menu var footer = "Footer Menu" -%}
{%- menu_items var links = prepend:main.items append:footer.items unique:true -%}
<nav>
{%- for link in links -%}
	<a href="{{ link.href }}"{% if link.open_in_new_tab %} target="_blank"{% endif %}>{{ link.name }}</a>
{%- endfor -%}
</nav>

    {% menu_items %} does not fetch anything: it builds a list from prepend and append, here the items of two menus, and unique drops an item that appears in both. It does not read limit, sort_by or the other fetching arguments. To show the items of a single menu, load the menu with {% menu %} and iterate menu.items directly.

    {{ menu_items }}

    Contains multiple menu_items.

    Properties
    Name Type Description
    object_type string Will always be menu_items
    is_valid boolean True if this contains at least one published menu_item
    output string The default output that the menu_items will produce when it is output directly to the template - using the "output_in_list" property of each menu_item in the items list
    prepended list List containing any prepended menu_items.
    fetched list List containing all of the menu_items that were fetched from the database (as opposed to prepended or appended).
    appended list List containing any appended menu_items.
    appended_unique list List containing any appended menu_items excluding any menu_items that are in either the list of prepended or fetched menu_items.
    items list List containing all of the combined menu_items from the prepended, fetched, and appended lists. If unique is true, this list will not contain any duplicates. If max_size is set, this list will not contain more than the number of menu_items specified.
    size integer The total number of menu_items in the items list, including prepended, fetched, and appended lists, and respecting the unique and max_size properties.
    max_size integer If set, this is the maximum number of items that will be returned in the items list and the maximum number of items that will be included when this menu_items object is enumerated as a list. When not set, this value will be 0.
    unique boolean When true, the items list will not contain any duplicates. Only the first instance of each menu_item will be included.
    limit integer The maximum number of items that were allowed to be in the list of fetched menu_items. May be 0 in some cases (such as when when there are no fetched menu_items.
    start integer The 1-based index of the first item in the list of fetched menu_items.
    page integer The 1-based index of the paginated results returned in the list of fetched menu_items, which is calculated from the start and limit parameters. Useful for paginated results.
    total_count integer The 1-based index of the first item in the list of fetched menu_items
    total_pages integer If any items were fetched from the database, total_pages will contain the number of paginated result pages in the database for the provided arguments. This may also be calculated using the total_count and limit properties.
    Example Load one menu_item and show its href and child items{% menu_item %} loads a single menu item by name or GUID; href, depth, and items describe the link and its children.
    Liquid
    {%- menu_item var link = "Products" -%}
{%- if link.is_valid -%}
	<a href="{{ link.href }}"{% if link.open_in_new_tab %} target="_blank"{% endif %}>{{ link.name }}</a>
	{%- if link.items.size > 0 -%}
		<ul>
		{%- for child in link.items -%}
			<li><a href="{{ child.href }}">{{ child.name }}</a></li>
		{%- endfor -%}
		</ul>
	{%- endif -%}
{%- endif -%}

    {% menu_item %} fetches a single menu item. Pass a name or GUID after the assignment target. Item-specific fields include href, open_in_new_tab, depth, order, items (child menu_items), and menu (the parent menu).

    Example Combine the items of two menus into one list{% menu_items %} builds a list from what you give prepend and append; it never fetches, so pass it the items you want.
    Liquid
    {%- menu var main = "Main Menu" -%}
{%- menu var footer = "Footer Menu" -%}
{%- menu_items var links = prepend:main.items append:footer.items unique:true -%}
<nav>
{%- for link in links -%}
	<a href="{{ link.href }}"{% if link.open_in_new_tab %} target="_blank"{% endif %}>{{ link.name }}</a>
{%- endfor -%}
</nav>

    {% menu_items %} does not fetch anything: it builds a list from prepend and append, here the items of two menus, and unique drops an item that appears in both. It does not read limit, sort_by or the other fetching arguments. To show the items of a single menu, load the menu with {% menu %} and iterate menu.items directly.

    {% menu_item %}

    {% menu_item output_to_template? [[var, set, or assign]? variable_name]? output_to_template? = value %}
    Parameters
    output_to_template optionalflag
    Include this flag to write the menu_item's output into the page at this point. What that output is differs by type, and for most types it is a built-in default that may change at any time, so see the output property of the menu_item object before relying on it. The flag may come before or after the variable name. When the call names no variable, the output is written whether or not the flag is present, which makes {% menu_item = value %} the smallest valid use of this method. When the call names a variable, the flag saves the menu_item to the variable and writes its output as well.
    var, set, or assign optionalkeyword
    Chooses the scope that holds the variable. var, the default, stores it in the current scope. set and assign can store it in outer scopes; Variable Scopes compares the three and when each fits.
    variable_name optionalvariable
    The variable that receives the menu_item. It may also be written as a reference, &name, which reads the variable's name from another variable (see Methods Overview). Leave it out to write the menu_item to the template instead.
    value requiredexpression
    Required; without a value the method call is not valid. Identifies which menu_item to fetch. It can evaluate to the menu_item itself, to its GUID, or to other text that identifies it, which for most types is its name; a type identified some other way, or only by GUID, says so in its summary. Names are matched without regard to case, but accented letters must match. A GUID identifies exactly one record, whereas when several records share a name, which of them is returned is not specified, so giving the records you fetch by name unique names avoids the question. A name reads better in a template and a GUID is exact; neither suits every site. When nothing matches, no error is raised: the variable holds an invalid menu_item, whose is_valid is false, so check is_valid before using it. When the expression itself has no value, for example an undefined variable, the method does nothing and the variable keeps any earlier value. May use liquid filters.

    Fetches a single {{ menu_item }}.

    Example Load one menu_item and show its href and child items{% menu_item %} loads a single menu item by name or GUID; href, depth, and items describe the link and its children.
    Liquid
    {%- menu_item var link = "Products" -%}
{%- if link.is_valid -%}
	<a href="{{ link.href }}"{% if link.open_in_new_tab %} target="_blank"{% endif %}>{{ link.name }}</a>
	{%- if link.items.size > 0 -%}
		<ul>
		{%- for child in link.items -%}
			<li><a href="{{ child.href }}">{{ child.name }}</a></li>
		{%- endfor -%}
		</ul>
	{%- endif -%}
{%- endif -%}

    {% menu_item %} fetches a single menu item. Pass a name or GUID after the assignment target. Item-specific fields include href, open_in_new_tab, depth, order, items (child menu_items), and menu (the parent menu).

    {% menu_items %}

    Builds a list from the prepend and append arguments alone, optionally without duplicates (unique). It never fetches menu items from the database, so limit, sorting, paging and filtering do not apply. To list the items of a menu, load the menu with {% menu %} and use its items, or combine the items of several menus with prepend and append.

    {% menu_items output_to_template? [[var, set, or assign]? variable_name]? output_to_template? = arguments %}
    Parameters
    output_to_template optionalflag
    Include this flag to write the menu_items list's output into the page here. That output is a built-in default for most types and may change at any time, so see the output property of the menu_items object before relying on it. The flag may come before or after the variable name. With no variable named, the output is written whether or not the flag is present; with one, the flag saves the list and writes its output too.
    var, set, or assign optionalkeyword
    Chooses the scope that holds the variable. var, the default, stores it in the current scope. set and assign can store it in outer scopes; Variable Scopes compares the three and when each fits.
    variable_name optionalvariable
    The variable that receives the menu_items list. It may also be written as a reference, &name, which reads the variable's name from another variable (see Methods Overview). Leave it out to write the list to the template instead.
    arguments requiredcollection
    Key:value pairs. May use the variable arguments syntax. Written after a required =. The name:value pairs choose which menu_items to fetch and how to narrow, order and page them. Nothing is fetched unless the call gives an argument other than prepend, append, unique, exclude_prepended, exclude_appended, max_size and cache_random; without one, the list holds only the prepended and appended menu_items.

    Options

    prepend optionallist
    May be a single menu_item, a list of menu_items, or the name or guid of one menu_item, to be included at the beginning of the menu_items list.
    append optionallist
    May be a single menu_item, a list of menu_items, or the name or guid of one menu_item, to be included at the end of the menu_items list.
    unique optionalboolean
    True to remove duplicates from each of the resulting lists (prepended, fetched, appended, and items), although there may be duplicates between the prepended, fetched, and appended lists. The "items" list will include objects in the order in which they appear - with prepended items first, then fetched items, then appended items.

    Builds a list of {{ menu_items }} from the prepend and append arguments; it does not fetch.

    Example Combine the items of two menus into one list{% menu_items %} builds a list from what you give prepend and append; it never fetches, so pass it the items you want.
    Liquid
    {%- menu var main = "Main Menu" -%}
{%- menu var footer = "Footer Menu" -%}
{%- menu_items var links = prepend:main.items append:footer.items unique:true -%}
<nav>
{%- for link in links -%}
	<a href="{{ link.href }}"{% if link.open_in_new_tab %} target="_blank"{% endif %}>{{ link.name }}</a>
{%- endfor -%}
</nav>

    {% menu_items %} does not fetch anything: it builds a list from prepend and append, here the items of two menus, and unique drops an item that appears in both. It does not read limit, sort_by or the other fetching arguments. To show the items of a single menu, load the menu with {% menu %} and iterate menu.items directly.