menu
Get a specific link list/menu by handle.
Query Structure
query {
menu(handle: String!) {
handle
levels
links {
title
url
links {
title
url
}
}
title
}
}
Arguments
Argument | Type | Description | Required | Default Value |
---|---|---|---|---|
handle | String | The handle of the link list to retrieve | Yes | N/A |
Return Type
Menu
Represents a navigational menu containing a list of links, typically used for site navigation structures such as main menus or footers.
Field | Type | Description |
---|---|---|
handle | String | Unique identifier (token) for this menu, used to reference the menu programmatically. |
levels | Int | The total number of nested levels in this menu, representing the depth of the menu hierarchy. |
links | [Link] | The list of top-level links in this menu. Each link may have its own child links, forming a hierarchical structure. |
title | String | The display name of the menu, typically shown as the menu’s title in navigation components. |
Link
Field | Type | Description |
---|---|---|
title | String | The display text of the link. |
url | String | The URL the link points to. |
links | [Link] | Child links nested under this link (optional). |
Examples
Basic Query
query {
menu(handle: "main-menu") {
title
links {
title
url
}
}
}
Advanced Query
query {
menu(handle: "footer-menu") {
handle
title
levels
links {
title
url
links {
title
url
}
}
}
}
Field Selection
query {
menu(handle: "sidebar-menu") {
title
links {
title
url
}
}
}
cURL Example
curl -X POST https://www.mystoreurl.com/graphql/0.8.0/ \
-H "Content-Type: application/json" \
-d '{"query":"query { menu(handle: \"main-menu\") { title links { title url } } }"}'
JavaScript Example
async function fetchMenu(handle) {
const query = `
query {
menu(handle: "${handle}") {
title
links {
title
url
}
}
}
`;
try {
const response = await fetch("https://www.mystoreurl.com/graphql/0.8.0/", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({ query })
});
const { data, errors } = await response.json();
if (errors) {
console.error("GraphQL errors:", errors);
return null;
}
return data.menu;
} catch (error) {
console.error("Network error:", error);
return null;
}
}
// Usage example
fetchMenu("main-menu").then(menu => {
if (menu) {
console.log("Menu title:", menu.title);
console.log("Links:", menu.links);
}
});
Response Format
{
"data": {
"menu": {
"handle": "main-menu",
"levels": 2,
"links": [
{
"title": "Home",
"url": "/",
"links": []
},
{
"title": "Products",
"url": "/products",
"links": [
{
"title": "New Arrivals",
"url": "/products/new-arrivals"
}
]
}
],
"title": "Main Menu"
}
}
}
Error Handling
Error Code | Description | Handling Recommendation |
---|---|---|
BAD_USER_INPUT | The provided handle argument is missing or invalid. | Verify the handle argument is provided and valid. |
NOT_FOUND | No menu found for the given handle. | Confirm the handle exists and is correctly spelled. |
INTERNAL_SERVER_ERROR | Unexpected server error occurred. | Retry the request after some time or contact support. |
Errors will be returned in the errors
array in the GraphQL response. Always check for errors before processing data.
Performance Considerations
- Query only the fields you need to reduce response size and improve performance.
- Avoid requesting deeply nested links unless necessary, as this can increase query complexity.
- Use pagination or limit nested levels if supported in future API versions to optimize performance.
- The API enforces rate limiting; excessive requests may result in throttling. Implement exponential backoff or retry logic.
- Responses may be cached by clients or intermediate proxies. Use cache headers if provided to improve efficiency.
Authentication
This API currently does not require authentication. However, authentication requirements may be introduced in future versions. Monitor API updates for any changes to authentication requirements.
Related Types
- Menu: The main return type representing the navigational menu.
- Link: Represents individual links within the menu, including nested child links.
Notes
- The
handle
argument is mandatory and must exactly match the menu’s unique identifier. - The
levels
field indicates the depth of nested links but does not provide the links themselves. - The
links
field may contain nestedlinks
arrays to represent submenus. - Always validate the presence of optional fields before accessing them in your application code.
Last updated on