Skip to main content
Light Dark System
Compact Comfortable

Priority List

<zn-priority-list> | ZnPriorityList
Since 1.0 experimental

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.

Bug Fixes
New Features
Documentation
Testing
<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>

Help Text

Add descriptive help text with the help-text attribute. For help text that contains HTML, use the help-text slot instead.

Database Migrations
Backend Services
Frontend App
CDN Cache Invalidation
<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.

Input Validation
Data Transformation
Data Enrichment
Storage
<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.

Development
Testing
Staging
Production
<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.

Critical
High
Medium
Low
<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.

Item A
Item B
Item C

Item A
Item B
Item C

Item A
Item B
Item C
<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.

First
Second
Third
<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.

Authentication
OAuth2 + SSO integration
Dashboard
Analytics and reporting
Public API
REST and GraphQL endpoints
Mobile App
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.

Deploy to Production
Code Review
Run Test Suite
<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.

1/12 100% reach it 1/12 81% reach it 1/12 64% reach it 58% reach it
<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.

Alpha
Beta
Gamma

Submit

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.

Red
Green
Blue

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>