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" 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" 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" 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>
Tile Items
Use zn-tile items for titled rows: the tile supplies the caption, description, icon square and
its own actions, and the list adds the handle, priority and ordering. A locked item stays where
it is and nothing can move past it. move-buttons adds up and down buttons to each movable item,
ahead of any controls in the item’s action-{value} slot. A tile with an href stays
clickable, underlining its caption on hover.
<zn-panel flush> <zn-priority-list label="Steps" flush move-buttons> <zn-tile value="offer" caption="Second chance" description="Offer · Default template · Student 20% (20%)" icon="tag@lu" icon-color="success"> <zn-chip slot="properties" icon="globe@lu" icon-size="12">1/12</zn-chip> <small slot="properties">100% reach it</small> </zn-tile> <zn-button slot="action-offer" icon="pencil@lu" icon-size="16" icon-button="small" plain tooltip="Edit"></zn-button> <zn-button slot="action-offer" icon="trash-2@lu" icon-size="16" icon-button="small" plain tooltip="Delete"></zn-button> <zn-tile value="message" caption="Before you go" href="#" description="Message · Retention copy" icon="message-square@lu" icon-color="ai"> <zn-chip slot="properties" icon="globe@lu" icon-size="12">1/12</zn-chip> <small slot="properties">81% reach it</small> </zn-tile> <zn-button slot="action-message" icon="pencil@lu" icon-size="16" icon-button="small" plain tooltip="Edit"></zn-button> <zn-button slot="action-message" icon="trash-2@lu" icon-size="16" icon-button="small" plain tooltip="Delete"></zn-button> <zn-tile value="survey" caption="Exit survey" description="Survey · Why are you leaving?" icon="circle-check@lu" icon-color="warning"> <zn-chip slot="properties" icon="globe@lu" icon-size="12">1/12</zn-chip> <small slot="properties">64% reach it</small> </zn-tile> <zn-button slot="action-survey" icon="pencil@lu" icon-size="16" icon-button="small" plain tooltip="Edit"></zn-button> <zn-button slot="action-survey" icon="trash-2@lu" icon-size="16" icon-button="small" plain tooltip="Delete"></zn-button> <zn-tile value="confirm" caption="Confirmation" description="Separate confirmation step · always the final step" locked> <small slot="properties">58% reach it</small> </zn-tile> </zn-priority-list> </zn-panel>
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
The list is a single tab stop. Arrow Up, Arrow Down, Home and End move focus between items; hold Alt to reorder:
- Alt + Arrow Up — Move the focused item up one position
- Alt + Arrow Down — Move the focused item down one position
- Alt + Home — Move the focused item to the top
- Alt + End — Move the focused item to the bottom
Locked items can’t be moved, and other items can’t move past them.
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@2.0.5/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@2.0.5/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). Use
zn-tile items for titled rows with their own actions. Set locked on an
item to pin it where it is.
|
action-{value}
|
Controls shown at the end of the item with that value. |
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
|
|
flush
|
Draws the items as rows divided edge to edge, for a list filling a flush panel; the label is kept for screen readers only. |
|
boolean
|
false
|
selectable
|
Lets a click or Enter select an item as well as drag it, for a list that doubles as navigation. The
click is passed on to the item, so a tab or link on it acts as if clicked.
|
|
boolean
|
false
|
selected
|
The selected item’s value. An item marked active by zn-tabs takes precedence, so the list follows its tabs. |
|
string
|
''
|
hidePriority
hide-priority
|
Hides each item’s priority number, for lists where the order shows the priority. |
|
boolean
|
false
|
moveButtons
move-buttons
|
Shows move up and move down buttons on each item. |
|
boolean
|
false
|
formAction
formaction
|
When set, the associated form will be submitted with the given action URL whenever items are reordered. If set to an empty string, the form will be submitted using its existing action. |
string
|
- | |
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-actions-gap |
The gap between an item’s slotted actions. Defaults to var(--zn-spacing-x-small).
|
|
--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-button><zn-dropdown><zn-example><zn-icon><zn-tooltip>