Skip to main content
Light Dark System

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" 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.

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

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>