Using Library Panels
1. Creating Library Panel
| Field | Description | Example |
|---|---|---|
| name | Name of the library panel | "Dashboard Stats" |
| description | Optional description of the panel | "Shows system stats" |
| model | Panel JSON model (from a saved panel) | |
| folderId | Folder ID where the library panel is stored | 123 |
Example: Creating a Library Panel via API
{
"name": "CPU Usage",
"description": "Graph showing CPU usage over time",
"model": {
"type": "graph",
"title": "CPU Usage",
"targets": [
{
"expr": "rate(node_cpu_seconds_total{mode='idle'}[5m])",
"legendFormat": "CPU Idle"
}
]
},
"folderId": 123
}
Note: The
model field should contain a valid panel JSON structure as exported from Grafana.
2. Adding Library Panel to Dashboard
| Step | Description | Action |
|---|---|---|
| 1 | Open the dashboard where you want to add the library panel | Click on the dashboard name in the Grafana UI |
| 2 | Enter edit mode | Click the "Edit" button in the top right corner of the dashboard |
| 3 | Locate the panel placement area | Click on the canvas area where you want to add the library panel |
| 4 | Select "Add Library Panel" | Choose from the available library panels in the panel list or search for a specific one |
| 5 | Configure the panel | Adjust settings like title, query, and other configurations as needed |
Example: Adding a Library Panel to Dashboard
{
"dashboard": {
"title": "My Dashboard",
"panels": [
{
"type": "library-panel",
"name": "CPU Usage Panel"
}
]
}
}3. Unlinking Library Panel
To unlink a library panel from a dashboard:
- Navigate to the dashboard containing the library panel.
- Click on the library panel to select it.
- Click the Unlink button in the panel options menu.
This action converts the library panel into a regular panel, allowing for independent customization.
Note: Unlinking a library panel removes its connection to the original library panel, and any future updates to the library panel will not affect this instance.
4. Updating Library Panel
| Property | Description | Values |
|---|---|---|
| name | Name of the library panel | string |
| description | Optional description of the library panel | string |
| model | JSON object representing the panel's configuration | object |
| folderId | ID of the folder where the library panel is stored | number |
| version | Version number of the library panel | number |
Example: Updating Library Panel
{
"name": "Updated Dashboard Panel",
"description": "A panel updated from the library",
"model": {
"title": "Updated Panel",
"type": "graph",
"datasource": "Prometheus"
},
"folderId": 123,
"version": 2
}5. Managing Library Panel Versions
| Version | Changes | Notes |
|---|---|---|
| v1.0 | Initial release of library panels | Basic panel linking and versioning capabilities |
| v2.0 | Enhanced version control | Support for semantic versioning and rollback features |
| v2.1 | Improved UI for version management | New dashboard view for library panel versions |
Example: Updating Library Panel Version
const libraryPanel = {
id: "12345",
version: "v2.1",
name: "System Metrics"
};
// Update to latest version
libraryPanel.version = "v2.1";
Note: When updating a library panel, ensure that all dependent dashboards are compatible with the new version.
6. Setting Library Panel Permissions
| Permission | Description | Scope | Default Role |
|---|---|---|---|
| librarypanel:read | Read access to library panels | Organization | Viewer, Editor, Admin |
| librarypanel:write | Write access to library panels (create, update, delete) | Organization | Editor, Admin |
| librarypanel:edit | Edit library panel content | Organization | Editor, Admin |
Example: Assigning Library Panel Permissions via API
curl -X POST "http://localhost:3000/api/access-control/users/1/permissions" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"librarypanel:read": true,
"librarypanel:write": false
}'
Note: Permissions can also be managed via the Grafana UI under
Configuration > Users > Permissions.
7. Searching Library Panels
| Field | Description | Example |
|---|---|---|
| query | Search term to filter library panels | dashboard |
| folderId | Filter by folder ID (optional) | 1 |
| limit | Maximum number of results to return (default: 1000) | 50 |
| includeUsed | Include panels that are currently used in dashboards | true |
Example: Search for Library Panels
const searchParams = {
query: 'dashboard',
folderId: 1,
limit: 50,
includeUsed: true
};
// Example API call to search library panels
fetch('/api/library-elements/search', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(searchParams)
})
.then(response => response.json())
.then(data => console.log(data));
8. Organizing Library Panels
Example: Creating a Folder Structure
{
"title": "Dashboard Library Panels",
"type": "folder",
"uid": "library-panels-folder"
}| Property | Description | Notes |
|---|---|---|
| folderUid | Unique identifier for the folder containing the panel | Required when organizing panels into folders |
| title | Name of the library panel | Must be unique within the folder |
| type | Must be "dashboard" | Library panels are always of type "dashboard" |
Best Practices for Organizing Library Panels
- Create a dedicated folder for library panels to keep them separate from regular dashboards
- Use descriptive titles that clearly indicate the panel's purpose or data source
- Organize panels into subfolders by category (e.g., "Database Metrics", "Application Logs")
- Use consistent naming conventions across all library panels
Note: Library panels can be organized into folders, but they cannot be nested within other folders.
Workflow: Moving a Library Panel to a Folder
- Navigate to the library panel you want to move
- Click on the "Edit" button in the top right corner
- In the panel settings, find the "Folder" field
- Select the target folder from the dropdown menu
- Save the changes to finalize the move
9. Exporting Library Panels
| Option | Values | Notes |
|---|---|---|
| libraryPanel.uid | string |
Unique identifier for the library panel |
| libraryPanel.name | string |
Name of the library panel |
| libraryPanel.model | object |
JSON representation of the panel's model |
| libraryPanel.folderId | number |
ID of the folder where the panel is stored |
| libraryPanel.version | number |
Version of the library panel |
Example: Exporting a Library Panel
{
"uid": "abc123",
"name": "CPU Usage Panel",
"model": {
"id": 1,
"title": "CPU Usage",
"type": "graph",
"datasource": "Prometheus"
},
"folderId": 5,
"version": 2
}
Note: The exported library panel can be imported into another Grafana instance or shared with other users.
10. Importing Library Panels
| Field | Description | Example |
|---|---|---|
| libraryPanel | Library panel to import | { name: 'Dashboard Stats', uid: 'abc123' } |
| dashboard | Target dashboard to import into | { id: 42, title: 'Production Dashboard' } |
| folder | Folder to store the imported panel | { id: 1, title: 'Shared Components' } |
Example: Importing a Library Panel via API
const importRequest = {
libraryPanel: {
name: 'Dashboard Stats',
uid: 'abc123'
},
dashboard: {
id: 42,
title: 'Production Dashboard'
},
folder: {
id: 1,
title: 'Shared Components'
}
};
fetch('/api/library-panels/import', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(importRequest)
});
Note: The library panel must already exist in the Grafana instance to be imported.
Warning: Importing a library panel into a dashboard will overwrite any existing panel with the same name.