strapi-plugin-navigation
Advanced tools
Create consumable navigation with a simple and straightforward visual builder
Strapi Navigation Plugin provides a website navigation / menu builder feature for Strapi Headless CMS admin panel. Navigation has the possibility to control the audience and can be consumed by the website with different output structure renderers:
As a ✅ verified plugin by Strapi team we're available on the Strapi Marketplace as well as In-App Marketplace where you can follow the installation instructions.
It's recommended to use yarn to install this plugin within your Strapi project. You can install yarn with these docs.
yarn add strapi-plugin-navigation@latest
After successful installation you've to re-build your Strapi instance. To archive that simply use:
yarn build
yarn develop
or just run Strapi in the development mode with --watch-admin option:
yarn develop --watch-admin
The UI Navigation plugin should appear in the Plugins section of Strapi sidebar after you run app again.
You can manage your multiple navigation containers by going to the Navigation manage view by clicking "Manage" button.
As a next step you must configure your the plugin by the way you want to. See Configuration section.
All done. Enjoy 🎉
Complete installation requirements are exact same as for Strapi itself and can be found in the documentation under Installation Requirements.
Supported Strapi versions:
This plugin is designed for Strapi v4 and is not working with v3.x. To get version for Strapi v3 install version v1.x.
We recommend always using the latest version of Strapi to start your new projects.
To start your journey with Navigation plugin you must first setup it using the dedicated Settings page (v2.0.3 and newer) or for any version, put your configuration in config/plugins.js. Anyway we're recommending the click-through option where your configuration is going to be properly validated.
v2.0.3 and newerVersion 2.0.3 introduces the intuitive Settings page which you can easily access via Strapi Settings -> Section: Navigation Plugin -> Configuration.
On the dedicated page, you will be able to set up all crucial properties which drive the plugin and customize each individual collection for which Navigation plugin should be enabled.
Note The default configuration for your plugin is fetched from
config/plugins.jsor, if the file is not there, directly from the plugin itself. If you would like to customize the default state to which you might revert, please follow the next section.
v2.0.2 and older + default configuration state for v2.0.3 and newerConfig for this plugin is stored as a part of the config/plugins.js or config/<env>/plugins.js file. You can use the following snippet to make sure that the config structure is correct. If you've got already configurations for other plugins stores by this way, you can use the navigation along with them.
Note v2.0.3 and newer only Changing this file will not automatically change plugin configuration. To synchronize plugin's config with plugins.js file, it is necessary to restore configuration through the settings page
Note for newer than v2.2.0
slugifyas been removed. THIS A BREAKING CHANGE
module.exports = ({ env }) => ({
// ...
navigation: {
enabled: true,
config: {
additionalFields: ['audience', { name: 'my_custom_field', type: 'boolean', label: 'My custom field' }],
contentTypes: ['api::page.page'],
contentTypesNameFields: {
'api::page.page': ['title']
},
pathDefaultFields: {
'api::page.page': ['slug']
},
allowedLevels: 2,
gql: {...},
}
}
});
additionalFields - Additional fields for navigation items. More here allowedLevels - Maximum level for which you're able to mark item as "Menu attached"contentTypes - UIDs of related content typescontentTypesNameFields - Definition of content type title fields like 'api::<collection name>.<content type name>': ['field_name_1', 'field_name_2'], if not set titles are pulled from fields like ['title', 'subject', 'name']. TIP - Proper content type uid you can find in the URL of Content Manager where you're managing relevant entities like: admin/content-manager/collectionType/< THE UID HERE >?page=1&pageSize=10&sort=Title:ASC&plugins[i18n][locale]=enpathDefaultFields - The attribute to copy the default path from per content type. Syntax: 'api::<collection name>.<content type name>': ['url_slug', 'path']gql - If you're using GraphQL that's the right place to put all necessary settings. More here i18nEnabled - should you want to manage multi-locale content via navigation set this value Enabled. More here cascadeMenuAttached - If you don't want "Menu attached" to cascade on child items set this value Disabled.slugify - allows to extend configuration of our "slugging" solution of choice. To learn more visit the documentation. It can be left unset since it's optional. This option can only be handled by configuration in config file.It is advised to configure additional fields through the plugin's Settings Page. There you can find the table of custom fields and toggle input for the audience field. When enabled, the audience field can be customized through the content manager. Custom fields can be added, edited, toggled, and removed with the use of the table provided on the Settings Page. When removing custom fields be advised that their values in navigation items will be lost. Disabling the custom fields will not affect the data and can be done with no consequence of loosing information.
Creating configuration for additional fields with the config.js file should be done with caution. Config object contains the additionalFields property of type Array<CustomField | 'audience'>, where CustomField is of type {type: 'string' | 'boolean', name: string, label: string}. When creating custom fields be advised that the name property has to be unique. When editing a custom field it is advised not to edit its name and type properties. After config has been restored the custom fields that are not present in config.js file will be deleted and their values in navigation items will be lost.
Using navigation with GraphQL requires both plugins to be installed and working. You can find installation guide for GraphQL plugin here. To properly configure GQL to work with navigation you should provide gql prop. This should contain union types that will be used to define GQL response format for your data while fetching:
Important! If you're using
config/plugins.jsto configure your plugins , please putnavigationproperty beforegraphql. Otherwise types are not going to be properly added to GraphQL Schema. That's because of dynamic types which base on plugin configuration which are added onbootstrapstage, notregister. This is not valid if you're usinggraphqlplugin without any custom configuration, so most of cases in real.
master: Int
items: [NavigationItem]
related: NavigationRelated
This prop should look as follows:
gql: {
navigationItemRelated: ['<your GQL related content types>'],
},
for example:
gql: {
navigationItemRelated: ['Page', 'UploadFile'],
},
where Page and UploadFile are your type names for the Content Types you're referring by navigation items relations.
This feature is opt-in.
In order to use this functionality setting default locale is required. (See: Settings -> Internationalization)
Once feature is enabled a restart is required. On server startup missing navigations for other locales will be created. From then you can manage navigation's localizations just like before.
If you want go back to pre-i18n way you can disable it in settings. Already created navigations will not be removed unless you make a choice for plugin to do so(this will require a restart).
If your newly created navigation localization is empty you can copy contents of one version's to the empty one. If related item is localized and locale version exists localization will be used as a related item. Otherwise plugin will fallback to an original item.
Shape of the rendered navigation will not change. Querying stays almost the same. To query for specific locale version just add locale query param. For example:
https://yourdomain.cool/api/navigation/render/1?locale=fr
or
https://yourdomain.cool/api/navigation/render/main-navigation?locale=fr
If locale is not specified whatever version used to be at id 1 will be returned.
Of course if you know that fr version is present at id 2 you can just query for that.
If feature is enabled GQL render navigation query is expanded to handle locale param(it will work the same as regular requests). Checkout schema provided by GraphQL plugin.
Plugin provides granular permissions based on Strapi RBAC functionality.
For any role different than Super Admin, to access the Navigation panel you must set following permissions:
{
"id": 1,
"title": "News",
"type": "INTERNAL",
"path": "news",
"externalPath": null,
"uiRouterKey": "News",
"menuAttached": false,
"parent": 8, // Parent Navigation Item 'id', null in case of root level
"master": 1, // Navigation 'id'
"createdAt": "2020-09-29T13:29:19.086Z",
"updatedAt": "2020-09-29T13:29:19.128Z",
"related": {/*<Content Type model >*/ },
"audience": []
}
{
"title": "News",
"menuAttached": true,
"path": "/news",
"type": "INTERNAL",
"uiRouterKey": "news",
"slug": "benefits",
"external": false,
"related": {
// <Content Type model >
},
"items": [
{
"title": "External url",
"menuAttached": true,
"path": "http://example.com",
"type": "EXTERNAL",
"uiRouterKey": "generic",
"external": true
},
// < Tree Navigation Item models >
]
}
{
"id": "News",
"title": "News",
"templateName": "pages:1",
"related": {
"contentType": "page",
"collectionName": "pages",
"id": 1
},
"path": "/news",
"slug": "news",
"parent": null, // Parent Navigation Item 'id', null in case of root level
"menuAttached": true
}
Plugin supports both REST API and GraphQL API exposed by Strapi.
Query Params
navigationIdOrSlug - ID or slug for which your navigation structure is generated like for REST API:
https://localhost:1337/api/navigation/render/1https://localhost:1337/api/navigation/render/main-menu
type - Enum value representing structure type of returned navigation:
https://localhost:1337/api/navigation/render/1?type=FLAT
menu (menuOnly for GQL) - Boolean value for querying only navigation items that are attached to menu should be rendered eg.
https://localhost:1337/api/navigation/render/1?menu=true
path - String value for querying navigation items by its path:
https://localhost:1337/api/navigation/render/1?path=/home/about-us
Important! Version
v2.0.13introduced breaking change! All responses have changed their structure. Related field will now be of type ContentType instead of Array<ContentType>
GET <host>/api/navigation/render/<navigationIdOrSlug>?type=<type>
Return a rendered navigation structure depends on passed type (TREE, RFR or nothing to render as FLAT).
The ID of navigation by default is
1, if you've got defined multiple navigations you must work with their IDs or Slugs to fetch.
Example URL: https://localhost:1337/api/navigation/render/1
Example response body
[
{
"id": 1,
"title": "News",
"type": "INTERNAL",
"path": "news",
"externalPath": null,
"uiRouterKey": "News",
"menuAttached": false,
"parent": null,
"master": 1,
"created_at": "2020-09-29T13:29:19.086Z",
"updated_at": "2020-09-29T13:29:19.128Z",
"related": {
"__contentType": "Page",
"id": 1,
"title": "News",
// ...
}
},
// ...
]
Example URL: https://localhost:1337/api/navigation/render/1?type=TREE
Example response body
[
{
"title": "News",
"menuAttached": true,
"path": "/news",
"type": "INTERNAL",
"uiRouterKey": "news",
"slug": "benefits",
"external": false,
"related": {
"__contentType": "Page",
"id": 1,
"title": "News",
// ...
},
"items": [
{
"title": "External url",
"menuAttached": true,
"path": "http://example.com",
"type": "EXTERNAL",
"uiRouterKey": "generic",
"external": true
},
// ...
]
},
// ...
]
Example URL: https://localhost:1337/api/navigation/render/1?type=RFR
Example response body
{
"pages": {
"News": {
"id": "News",
"title": "News",
"templateName": "pages:1",
"related": {
"contentType": "page",
"collectionName": "pages",
"id": 1
},
"path": "/news",
"slug": "news",
"parent": null,
"menuAttached": true
},
"Community": {
"id": "Community",
"title": "Community",
"templateName": "pages:2",
"related": {
"contentType": "page",
"collectionName": "pages",
"id": 2
},
"path": "/community",
"slug": "community",
"parent": null,
"menuAttached": true
},
"Highlights": {
"id": "Highlights",
"title": "Highlights",
"templateName": "pages:3",
"related": {
"contentType": "page",
"collectionName": "pages",
"id": 3
},
"path": "/community/highlights",
"slug": "community-highlights",
"parent": "Community",
"menuAttached": false
},
// ...
},
"nav": {
"root": [
{
"label": "News",
"type": "internal",
"page": "News"
},
{
"label": "Community",
"type": "internal",
"page": "Community"
},
{
"label": "External url",
"type": "external",
"url": "http://example.com"
},
// ...
],
"Community": [
{
"label": "Highlights",
"type": "internal",
"page": "Highlights"
},
// ...
],
// ...
}
}
Same as REST API returns a rendered navigation structure depends on passed type (TREE, RFR or nothing to render as FLAT).
Example request
query {
renderNavigation(
navigationIdOrSlug: "main-navigation"
type: TREE
menuOnly: false
) {
id
title
path
related {
id
attributes {
__typename
... on Page {
Title
}
... on WithFlowType {
Name
}
}
}
items {
id
title
path
related {
id
attributes {
__typename
... on Page {
Title
}
... on WithFlowType {
Name
}
}
}
}
}
}
Example response
{
"data": {
"renderNavigation": [
{
"id": 8,
"title": "Test page",
"path": "/test-path",
"related": {
"id": 3,
"attributes": {
"__typename": "WithFlowType",
"Name": "Test"
}
},
"items": [
{
"id": 11,
"title": "Nested",
"path": "/test-path/nested-one",
"related": {
"id": 1,
"attributes": {
"__typename": "Page",
"Title": "Eg. Page title"
}
}
}
]
},
{
"id": 10,
"title": "Another page",
"path": "/another",
"related": {
"__typename": "Page",
"Title": "Eg. Page title"
},
"items": []
}
]
}
}
Depending on a content type templateName will be resolved differently
For collection types it will be read from content type's attribute name template holding a component which definition has option named templateName.
For single types a global name of this content type will be used as a template name or it can be set manually with an option named templateName.
Live example of plugin usage can be found in the VirtusLab Strapi Examples repository.
Q: I would like to use GraphQL schemas but I'm not getting renderNavigation query or even proper types as Navigation, NavigationItem etc. What should I do?
A: A: There is a one trick you might try. Strapi by default is ordering plugins by the way which takes strapi-plugin-graphql to initialize earlier than other plugins so types might not be injected. If you don't have it yet, please create config/plugins.js file and put there following lines (put graphql at the end):
module.exports = {
'navigation': { enabled: true },
'graphql': { enabled: true },
};
If you already got it, make sure that navigation plugin is inserted before graphql. That should do the job.
Slug generation is available as a controller and service. If you have custom requirements outside of what this plugin provides you can add your own logic with plugins extensions.
For example:
// path: ./src/index.js
module.exports = {
// ...
bootstrap({ strapi }) {
const navigationCommonService = strapi.plugin("navigation").service("common");
const originalGetSlug = navigationCommonService.getSlug;
const preprocess = (q) => {
return q + "suffix";
};
navigationCommonService.getSlug = (query) => {
return originalGetSlug(preprocess(query));
};
},
};
Feel free to fork and make a Pull Request to this plugin project. All the input is warmly welcome!
Clone repository
git clone git@github.com:VirtusLab-Open-Source/strapi-plugin-navigation.git
Create a soft link in your strapi project to plugin build folder
ln -s <...>/strapi-plugin-navigation/build <...>/strapi-project/src/plugins/navigation
Run build command
// Watch for file changes
yarn develop
// or run build without nodemon
yarn build:dev
For general help using Strapi, please refer to the official Strapi documentation. For additional help, you can use one of these channels to ask a question:
[VirtusLab] prefix and DM.MIT License Copyright (c) VirtusLab Sp. z o.o. & Strapi Solutions.
FAQs
Strapi - Navigation plugin
The npm package strapi-plugin-navigation receives a total of 2,887 weekly downloads. As such, strapi-plugin-navigation popularity was classified as popular.
We found that strapi-plugin-navigation demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.