OrderedPicker

<caos-ordered-picker>

choose several values from a list and put them in order, in two lists side by side

May be placed on a page inside an app and a step of a guided flow.

Inputs

Name	Attribute	Description	Type	Default	Required
`options`	property only	Everything that could be chosen, as { value, label, qualifier? } objects or plain strings. The available list shows the ones not chosen, in this order. A qualifier is a quieter second line under the label.	json	none declared	Optional
`value`	property only	What is chosen, as a list of option values in order. It is written back on every change. A value that is not among the options stays in the chosen list, marked, until somebody removes it.	json	none declared	Optional
`locked`	property only	Values that are chosen and cannot be removed. Any not already in value are added to its end; each is drawn with a lock, and Remove refuses it.	json	none declared	Optional
`min`	`min`, also a property	The fewest values that make a complete choice. A removal below it is allowed — swapping one entry for another passes through one too few — but the picker says how many are needed until it holds again.	number	none declared	Optional
`max`	`max`, also a property	The most values that can be chosen. Adding stops there, and the picker says why.	number	none declared	Optional
`label`	`label`, markup only	What is being chosen, drawn above both lists and read as the first half of each list’s name.	text	none declared	Optional
`availableLabel`	`available-label`, markup only	The heading over the list of what could be added.	text	Available	Optional
`chosenLabel`	`chosen-label`, markup only	The heading over the chosen list — the place to say what its order means.	text	Chosen	Optional
`message`	`message`, markup only	Helper text under the lists. A minimum or maximum that is in play says its own sentence instead.	text	none declared	Optional
`disabled`	`disabled`, also a property	The choice may be read but not changed: both lists and every button are refused.	boolean	false	Optional

Events

Name	When it fires	What it carries
`change`	An entry is added, removed or moved — by a button, the keyboard or a double-click — after value has been written back. Setting options, value or locked raises nothing.	nothing — read value off the element.

Slots

Nothing goes inside this piece.

Styling hooks

Design token	What it controls
`--caos-font`	The typeface of the label, the headings, the entries and the message.
`--caos-text-body`	The size of the label above the lists.
`--caos-text-row`	The size of each entry.
`--caos-space-1`	The padding inside each list, and the gap between a heading and its list.
`--caos-space-2`	The gap between the lists and the buttons, and the padding of each entry.
`--caos-radius`	The corners of the lists and the buttons.
`--caos-radius-sm`	The corners of an entry’s highlight.
`--caos-color-border`	The edge of the lists and the buttons.
`--caos-color-border-strong`	The edge of a button under the pointer.
`--caos-color-surface`	The fill of the lists.
`--caos-color-surface-2`	The fill of the buttons, and of an entry under the pointer.
`--caos-state-selected-bg`	The fill of the highlighted entry in each list.
`--caos-color-text`	The entry labels and the button chevrons.
`--caos-color-text-muted`	The label, the headings, the position numbers, qualifiers, the lock and the message.
`--caos-color-danger`	The mark on a value that is not among the options, and a minimum not yet met.
`--caos-focus-ring`	The ring on a list or a button reached by keyboard.

Methods

Nothing else drives this piece by calling it.

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
`::part(picker)`	the whole piece	Always
`::part(label)`	the label above the lists	Always
`::part(heading)`	the heading over each list	Always
`::part(listbox)`	each of the two lists	Always
`::part(option)`	one entry in either list	Always
`::part(rank)`	the position number of a chosen entry	Always
`::part(button)`	the add, remove, move up and move down buttons	Always
`::part(message)`	the line under the lists	Always

When to use it

Several values are chosen AND their order is part of the answer — the columns a list shows, the entries pinned in a stack, a ranked shortlist — or some values have to stay chosen, or the number chosen has limits.

What to use instead

PicklistField — The order means nothing: several values from one declared list is the picklist field with multiple set, a group of checkboxes that shows every option at once.
PillContainer — The chosen values are only being shown, as a row of tags.
LookupField — What is chosen is a record, searched for live rather than listed.

Accessibility

Each list is a real role="listbox", named by the label and its own heading and described by the message, with aria-activedescendant following the highlight so an entry is announced without focus leaving the list. Arrow Up, Arrow Down, Home and End move; Enter or Space moves the highlighted entry across; Alt with an arrow moves a chosen entry up or down. Every button carries an accessible name, a locked entry carries the words “Required, cannot be removed”, and the minimum and maximum sentences are announced as they appear. The position numbers are hidden from assistive technology, which counts an option’s place itself. Left to the author: option labels that tell entries apart, and headings that say what the lists mean when “Available” and “Chosen” do not.

Examples

Choosing and ordering

Nothing chosen to begin with: columns picked from the list on the left and put in order on the right.

{
  "id": "example",
  "section": "Choosing and ordering",
  "columns": 1,
  "items": [
    {
      "id": "ordered_picker_1",
      "type": "component",
      "key": "ordered_picker",
      "inputs": {
        "label": "Columns",
        "options": [
          {
            "value": "name",
            "label": "Name"
          },
          {
            "value": "account",
            "label": "Account"
          },
          {
            "value": "stage",
            "label": "Stage"
          },
          {
            "value": "owner",
            "label": "Owner"
          },
          {
            "value": "amount",
            "label": "Amount"
          },
          {
            "value": "close_date",
            "label": "Close date"
          }
        ]
      }
    }
  ]
}

<caos-ordered-picker id="orderedPicker1" label="Columns"></caos-ordered-picker>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const orderedPicker1 = document.getElementById('orderedPicker1');
orderedPicker1.options = [
  {
    "value": "name",
    "label": "Name"
  },
  {
    "value": "account",
    "label": "Account"
  },
  {
    "value": "stage",
    "label": "Stage"
  },
  {
    "value": "owner",
    "label": "Owner"
  },
  {
    "value": "amount",
    "label": "Amount"
  },
  {
    "value": "close_date",
    "label": "Close date"
  }
];

Some already chosen

Opens with three columns chosen, in the order they show, beside the ones that could still be added.

{
  "id": "example",
  "section": "Some already chosen",
  "columns": 1,
  "items": [
    {
      "id": "ordered_picker_1",
      "type": "component",
      "key": "ordered_picker",
      "inputs": {
        "label": "Columns",
        "available_label": "Available columns",
        "chosen_label": "Shown, left to right",
        "options": [
          {
            "value": "name",
            "label": "Name"
          },
          {
            "value": "account",
            "label": "Account"
          },
          {
            "value": "stage",
            "label": "Stage"
          },
          {
            "value": "owner",
            "label": "Owner"
          },
          {
            "value": "amount",
            "label": "Amount"
          },
          {
            "value": "close_date",
            "label": "Close date"
          }
        ],
        "value": [
          "name",
          "stage",
          "amount"
        ]
      }
    }
  ]
}

<caos-ordered-picker id="orderedPicker1" label="Columns" available-label="Available columns" chosen-label="Shown, left to right"></caos-ordered-picker>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const orderedPicker1 = document.getElementById('orderedPicker1');
orderedPicker1.options = [
  {
    "value": "name",
    "label": "Name"
  },
  {
    "value": "account",
    "label": "Account"
  },
  {
    "value": "stage",
    "label": "Stage"
  },
  {
    "value": "owner",
    "label": "Owner"
  },
  {
    "value": "amount",
    "label": "Amount"
  },
  {
    "value": "close_date",
    "label": "Close date"
  }
];
orderedPicker1.value = [
  "name",
  "stage",
  "amount"
];

Values that stay chosen

The record name is locked in: it carries a lock, and Remove refuses it however it is asked.

{
  "id": "example",
  "section": "Values that stay chosen",
  "columns": 1,
  "items": [
    {
      "id": "ordered_picker_1",
      "type": "component",
      "key": "ordered_picker",
      "inputs": {
        "label": "Columns",
        "options": [
          {
            "value": "name",
            "label": "Name"
          },
          {
            "value": "account",
            "label": "Account"
          },
          {
            "value": "stage",
            "label": "Stage"
          },
          {
            "value": "owner",
            "label": "Owner"
          },
          {
            "value": "amount",
            "label": "Amount"
          },
          {
            "value": "close_date",
            "label": "Close date"
          }
        ],
        "value": [
          "name",
          "owner"
        ],
        "locked": [
          "name"
        ]
      }
    }
  ]
}

<caos-ordered-picker id="orderedPicker1" label="Columns"></caos-ordered-picker>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const orderedPicker1 = document.getElementById('orderedPicker1');
orderedPicker1.options = [
  {
    "value": "name",
    "label": "Name"
  },
  {
    "value": "account",
    "label": "Account"
  },
  {
    "value": "stage",
    "label": "Stage"
  },
  {
    "value": "owner",
    "label": "Owner"
  },
  {
    "value": "amount",
    "label": "Amount"
  },
  {
    "value": "close_date",
    "label": "Close date"
  }
];
orderedPicker1.value = [
  "name",
  "owner"
];
orderedPicker1.locked = [
  "name"
];

At least two, at most four

With one region chosen the picker asks for another; at four, adding stops and it says why.

{
  "id": "example",
  "section": "At least two, at most four",
  "columns": 1,
  "items": [
    {
      "id": "ordered_picker_1",
      "type": "component",
      "key": "ordered_picker",
      "inputs": {
        "label": "Regions",
        "options": [
          {
            "value": "north",
            "label": "North"
          },
          {
            "value": "south",
            "label": "South"
          },
          {
            "value": "east",
            "label": "East"
          },
          {
            "value": "west",
            "label": "West"
          },
          {
            "value": "central",
            "label": "Central"
          },
          {
            "value": "overseas",
            "label": "Overseas"
          }
        ],
        "value": [
          "north"
        ],
        "min": 2,
        "max": 4
      }
    }
  ]
}

<caos-ordered-picker id="orderedPicker1" label="Regions" min="2" max="4"></caos-ordered-picker>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const orderedPicker1 = document.getElementById('orderedPicker1');
orderedPicker1.options = [
  {
    "value": "north",
    "label": "North"
  },
  {
    "value": "south",
    "label": "South"
  },
  {
    "value": "east",
    "label": "East"
  },
  {
    "value": "west",
    "label": "West"
  },
  {
    "value": "central",
    "label": "Central"
  },
  {
    "value": "overseas",
    "label": "Overseas"
  }
];
orderedPicker1.value = [
  "north"
];

A chosen value no longer offered

A pinned entry whose package has gone stays in the chosen list, marked, until somebody takes it out.

{
  "id": "example",
  "section": "A chosen value no longer offered",
  "columns": 1,
  "items": [
    {
      "id": "ordered_picker_1",
      "type": "component",
      "key": "ordered_picker",
      "inputs": {
        "label": "Edge tabs",
        "available_label": "Not pinned",
        "chosen_label": "Pinned, in this order",
        "options": [
          {
            "value": "report_a_bug",
            "label": "Report a Bug"
          },
          {
            "value": "guidance",
            "label": "Guidance Center"
          }
        ],
        "value": [
          "guidance",
          "retired_assistant"
        ]
      }
    }
  ]
}

<caos-ordered-picker id="orderedPicker1" label="Edge tabs" available-label="Not pinned" chosen-label="Pinned, in this order"></caos-ordered-picker>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const orderedPicker1 = document.getElementById('orderedPicker1');
orderedPicker1.options = [
  {
    "value": "report_a_bug",
    "label": "Report a Bug"
  },
  {
    "value": "guidance",
    "label": "Guidance Center"
  }
];
orderedPicker1.value = [
  "guidance",
  "retired_assistant"
];