Priority List
<zn-priority-list> | ZnPriorityList
A reorderable list where each item receives a numerical priority based on its position. Supports drag-and-drop and keyboard reordering. Priority values are submitted as form data via hidden inputs.
Examples
Basic Priority List
Use the label attribute to give the list an accessible label. Each child element must have a
value attribute that uniquely identifies it.
<zn-priority-list label="Task Priority"> <div value="bug-fixes">Bug Fixes</div> <div value="new-features">New Features</div> <div value="documentation">Documentation</div> <div value="testing">Testing</div> </zn-priority-list>
This component works with standard <form> elements. Please refer to the section on
form controls to learn more about form submission and
client-side validation.
Help Text
Add descriptive help text with the help-text attribute. For help text that contains HTML, use
the help-text slot instead.
<zn-priority-list label="Deployment Order" help-text="Drag items to set the deployment sequence"> <div value="database">Database Migrations</div> <div value="backend">Backend Services</div> <div value="frontend">Frontend App</div> <div value="cdn">CDN Cache Invalidation</div> </zn-priority-list>
Label with Tooltip
Use the label-tooltip attribute to add text that appears in a tooltip triggered by an info icon
next to the label.
<zn-priority-list label="Processing Order" label-tooltip="Items will be processed from highest to lowest priority" help-text="Drag to reorder"> <div value="validation">Input Validation</div> <div value="transform">Data Transformation</div> <div value="enrichment">Data Enrichment</div> <div value="storage">Storage</div> </zn-priority-list>
Initial Order
Use the order attribute to define the initial display order as a comma-separated list of item
keys. Items not listed in order are appended at the end in their DOM order.
<zn-priority-list label="Release Pipeline" order="testing,staging,production,development"> <div value="development">Development</div> <div value="testing">Testing</div> <div value="staging">Staging</div> <div value="production">Production</div> </zn-priority-list>
Custom Priority Start
Use the priority-start attribute to change the starting priority number. This is useful when
priorities don’t start at 1.
<zn-priority-list label="Priority Queue" priority-start="0"> <div value="critical">Critical</div> <div value="high">High</div> <div value="medium">Medium</div> <div value="low">Low</div> </zn-priority-list>
Sizes
Use the size attribute to change the size of the list items.
<zn-priority-list label="Small" size="small"> <div value="a">Item A</div> <div value="b">Item B</div> <div value="c">Item C</div> </zn-priority-list> <br /> <zn-priority-list label="Medium" size="medium"> <div value="a">Item A</div> <div value="b">Item B</div> <div value="c">Item C</div> </zn-priority-list> <br /> <zn-priority-list label="Large" size="large"> <div value="a">Item A</div> <div value="b">Item B</div> <div value="c">Item C</div> </zn-priority-list>
Disabled
Use the disabled attribute to prevent reordering.
<zn-priority-list label="Locked Order" disabled> <div value="first">First</div> <div value="second">Second</div> <div value="third">Third</div> </zn-priority-list>
Rich Content
Slotted items can contain any HTML content, not just text.
OAuth2 + SSO integration
Analytics and reporting
REST and GraphQL endpoints
iOS and Android support
<zn-priority-list label="Feature Roadmap"> <div value="auth"> <strong>Authentication</strong> <br /><small>OAuth2 + SSO integration</small> </div> <div value="dashboard"> <strong>Dashboard</strong> <br /><small>Analytics and reporting</small> </div> <div value="api"> <strong>Public API</strong> <br /><small>REST and GraphQL endpoints</small> </div> <div value="mobile"> <strong>Mobile App</strong> <br /><small>iOS and Android support</small> </div> </zn-priority-list>
Item Actions
Use the action-{value} slot to add interactive elements (buttons, links, etc.) to the right
side of each item. Actions are fully clickable and won’t interfere with drag behaviour.
<zn-priority-list id="action-list" label="Task Queue"> <div value="deploy">Deploy to Production</div> <zn-button slot="action-deploy" size="small" variant="text" theme="danger" onclick="this.closest('zn-priority-list').querySelector('[value=deploy]').remove()"> <zn-icon src="delete" size="16"></zn-icon> </zn-button> <div value="review">Code Review</div> <zn-button slot="action-review" size="small" variant="text" theme="danger" onclick="this.closest('zn-priority-list').querySelector('[value=review]').remove()"> <zn-icon src="delete" size="16"></zn-icon> </zn-button> <div value="test">Run Test Suite</div> <zn-button slot="action-test" size="small" variant="text" theme="danger" onclick="this.closest('zn-priority-list').querySelector('[value=test]').remove()"> <zn-icon src="delete" size="16"></zn-icon> </zn-button> </zn-priority-list>
Form Submission
When a name is set, the component generates hidden inputs for each item as
name[itemValue]=priority. This example shows the submitted form data.
Submit the form to see the data
<form id="priority-form"> <zn-priority-list name="priority" label="Reorder and Submit"> <div value="alpha">Alpha</div> <div value="beta">Beta</div> <div value="gamma">Gamma</div> </zn-priority-list> <br /> <zn-button type="submit">Submit</zn-button> </form> <br /> <pre id="priority-output">Submit the form to see the data</pre> <script type="module"> const form = document.getElementById('priority-form'); const output = document.getElementById('priority-output'); form.addEventListener('submit', event => { event.preventDefault(); const formData = new FormData(form); const entries = [...formData.entries()].map(([key, val]) => `${key} = ${val}`); output.textContent = entries.join('\n'); }); </script>
Listening for Changes
Use the zn-reorder event to react to order changes. Call getPriorityMap() on the
component to get the current priority assignments.
Reorder items to see the priority map
<zn-priority-list id="event-list" label="Reorder to see events"> <div value="red">Red</div> <div value="green">Green</div> <div value="blue">Blue</div> </zn-priority-list> <br /> <pre id="event-output">Reorder items to see the priority map</pre> <script type="module"> const list = document.getElementById('event-list'); const output = document.getElementById('event-output'); list.addEventListener('zn-reorder', () => { const map = list.getPriorityMap(); output.textContent = JSON.stringify(map, null, 2); }); </script>
Keyboard Navigation
Focus any item and use the keyboard to reorder:
- Arrow Up — Move the focused item up one position
- Arrow Down — Move the focused item down one position
- Home — Move the focused item to the top
- End — Move the focused item to the bottom
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.91/dist/components/priority-list/priority-list.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.91/dist/components/priority-list/priority-list.js';
To import this component using a bundler:
import '@kubex/zinc/dist/components/priority-list/priority-list.js';
Slots
| Name | Description |
|---|---|
| (default) |
The default slot where list items are placed. Each slotted element must have a
value attribute that uniquely identifies the item. The component automatically assigns
slot names to project each item into the correct position. The item’s position in the list
determines its priority (top = priority-start, incrementing).
|
label
|
The component’s label. Required for proper accessibility. Alternatively, use the
label attribute.
|
label-tooltip
|
Used to add text displayed in a tooltip next to the label. |
help-text
|
Text that describes how to use the component. Alternatively, use the
help-text attribute.
|
Learn more about using slots.
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
name
|
The name prefix for form submission. Each item generates a hidden input named
{name}[{itemValue}]
with the priority number as its value.
|
string
|
''
|
|
value
|
The current ordered list of item keys, reflecting the visual order. This is the source of truth for
ordering. Each entry should match a value attribute on a slotted child element.
|
string[]
|
- | |
label
|
The component’s label. Required for proper accessibility. |
string
|
''
|
|
labelTooltip
label-tooltip
|
Text that appears in a tooltip next to the label. |
string
|
''
|
|
helpText
help-text
|
Help text that describes how to use the component. |
string
|
''
|
|
form
|
Associates the control with a form by id. The form must be in the same document or shadow root. |
|
string
|
''
|
size
|
The size of the list items. |
|
'small' | 'medium' | 'large'
|
'medium'
|
disabled
|
Whether the priority list is disabled. |
|
boolean
|
false
|
required
|
Ensures the form control has a value before allowing submission. |
|
boolean
|
false
|
priorityStart
priority-start
|
The starting priority number. Defaults to 1. |
number
|
1
|
|
order
|
A comma-separated list of item keys defining the initial display order. Keys must match the
value attributes on slotted children. Any slotted items not listed are appended at the
end in DOM order.
|
string
|
''
|
|
validity
|
Gets the validity state object. |
ValidityState
|
- | |
validationMessage
|
Gets the validation message. |
string
|
- | |
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
zn-change |
|
Emitted when the order of items changes. | - |
zn-reorder |
|
Emitted when items are reordered. Call getPriorityMap() on the component to get the
updated { key: string, priority: number }[] array.
|
- |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
getPriorityMap() |
Returns the priority map: an array of { key, priority } objects. | - |
checkValidity() |
Checks for validity but does not show a validation message. | - |
getForm() |
Gets the associated form, if one exists. | - |
reportValidity() |
Checks for validity and shows the browser’s validation message if the control is invalid. | - |
setCustomValidity() |
Sets a custom validation message. Pass an empty string to restore validity. |
_message:
|
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--zn-priority-list-item-gap |
The gap between list items. Defaults to var(--zn-spacing-2x-small). |
|
--zn-priority-list-item-padding |
The padding inside each item. Defaults to
var(--zn-spacing-small) var(--zn-spacing-medium).
|
|
--zn-priority-list-handle-color |
The color of the drag handle. Defaults to var(--zn-color-neutral-500). |
|
--zn-priority-list-priority-color |
The color of the priority number. Defaults to var(--zn-color-neutral-600). |
Learn more about customizing CSS custom properties.
Parts
| Name | Description |
|---|---|
form-control |
The form control wrapper. |
form-control-label |
The label wrapper. |
form-control-input |
The input area wrapper. |
form-control-help-text |
The help text wrapper. |
list |
The list container. |
item |
An individual list item row. |
drag-handle |
The drag handle icon. |
priority |
The priority number badge. |
content |
The content area of an item. |
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
<zn-example><zn-icon>