Transfer List

Use CTransferList when people need to compare a finite set of available items with an ordered chosen set. CTransferListItem declares stable values, plain accessible labels, optional rich presentation, and disabled state.

Move items between two lists

The enhanced component uses two labeled multi-select listboxes and explicit buttons. Without JavaScript, the same values remain available through a native select[multiple] form control.

Choose and order reviewers

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TransferListAtAGlance(Component):
    template = """
      <c-CTransferList name="reviewers" c-value="['grace']">
        <c-CTransferListItem value="ada" label="Ada Lovelace" />
        <c-CTransferListItem value="grace" label="Grace Hopper" />
        <c-CTransferListItem value="katherine" label="Katherine Johnson" />
        <c-CTransferListItem value="margaret" label="Margaret Hamilton" />
      </c-CTransferList>
    """


preview = TransferListAtAGlance()
preview  # noqa: B018

Selection inside a pane is separate from the chosen form value. Select one or more enabled options, then use Add or Remove. The Add all and Remove all buttons can be omitted with show_move_all=False. Chosen items retain the exact order in value and in submitted form entries.

Render rich, noninteractive items

The Item default slot can replace its visible label with server-rendered presentation. Keep label plain and descriptive because native fallback, typeahead, and assistive naming use it.

Render rich Transfer List items

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TransferListRichItems(Component):
    template = """
      <c-CTransferList name="owners" c-value="['platform']">
        <c-CTransferListItem value="platform" label="Platform team">
          <strong>Platform</strong><br /><small>Runtime and release infrastructure</small>
        </c-CTransferListItem>
        <c-CTransferListItem value="design" label="Design systems team">
          <strong>Design systems</strong><br /><small>Components, tokens, and accessibility</small>
        </c-CTransferListItem>
        <c-CTransferListItem value="security" label="Security team" c-disabled="True">
          <strong>Security</strong><br /><small>Managed by policy</small>
        </c-CTransferListItem>
      </c-CTransferList>
    """


preview = TransferListRichItems()
preview  # noqa: B018

Do not place links, buttons, inputs, editable content, or other focus stops inside an Item. The family follows the listbox interaction model and rejects interactive descendants during enhancement.

Control chosen values from Alpine

Pass value and onValueChange through $c-props for controlled state. Transfer and reorder actions become requests: the visible order changes only after the owner accepts the proposed array.

Control a Transfer List

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TransferListControlled(Component):
    template = """
      <section x-data="{chosen:['grace'],last:'No request'}">
        <c-CTransferList
          $c-props="{
            value:chosen,
            onValueChange:(next,detail)=>{chosen=next;last=`${detail.source}: ${next.join(', ') || 'none'}`},
          }"
        >
          <c-CTransferListItem value="ada" label="Ada" />
          <c-CTransferListItem value="grace" label="Grace" />
          <c-CTransferListItem value="katherine" label="Katherine" />
        </c-CTransferList>
        <output x-text="last">No request</output>
      </section>
    """


preview = TransferListControlled()
preview  # noqa: B018

Omit client value, or set it to null, for uncontrolled behavior. In that mode an accepted action updates the native form owner, emits native input then change, and calls onValueChange.

Submit and validate forms

Set name to submit one entry per chosen item in chosen order. form can associate the control with a non-ancestor form. required=True requires at least one chosen value and moves focus to the chosen list when native validation fails.

Submit a required ordered selection

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TransferListForm(Component):
    template = """
      <form x-data="{result:'Not submitted'}"
        @submit.prevent="result=[...new FormData($el).getAll('reviewers')].join(' → ')"
      >
        <c-CTransferList name="reviewers" c-required="True" c-value="['ada']">
          <c-CTransferListItem value="ada" label="Ada" />
          <c-CTransferListItem value="grace" label="Grace" />
          <c-CTransferListItem value="katherine" label="Katherine" />
        </c-CTransferList>
        <p><button type="submit">Submit order</button> <button type="reset">Reset</button></p>
        <output x-text="result">Not submitted</output>
      </form>
    """


preview = TransferListForm()
preview  # noqa: B018

Native reset restores the server-rendered value. A disabled Item cannot be moved or reordered. An initially chosen disabled Item remains submitted by the native fallback through an ordered hidden option proxy.

Keyboard and accessibility

Each pane has one tab stop and an active descendant. Arrow keys, Home, End, typeahead, Space, Enter, Shift+Arrow range selection, and Ctrl/Cmd+A are available. Explicit transfer and reorder buttons remain reachable in normal tab order, so drag and drop is never required.

Use disabled items and accessible labels

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TransferListAccessibility(Component):
    template = """
      <c-CTransferList
        name="permissions"
        available_label="Available permissions"
        chosen_label="Granted permissions"
        c-value="['audit','read']"
      >
        <c-CTransferListItem value="read" label="Read records" />
        <c-CTransferListItem value="write" label="Write records" />
        <c-CTransferListItem value="audit" label="Audit access required by policy" c-disabled="True">
          <strong>Audit access</strong><br /><small>Required by policy; cannot be removed</small>
        </c-CTransferListItem>
      </c-CTransferList>
    """


preview = TransferListAccessibility()
preview  # noqa: B018

The family announces accepted moves and reorders through a polite live region. Pane labels, counts, controls, empty states, announcements, and required validation use Citry UI catalog messages by default. Any explicit *_label input belongs to the caller and does not switch with the Citry client locale.

Responsive layout and customization

The three-column layout stacks automatically in a narrow container and uses logical CSS properties for RTL. Customize the root and Items with class_, style, and attrs, or use the documented public variables and part selectors.

Customize Transfer List

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TransferListCustomization(Component):
    template = """
      <c-CTransferList class_="brand-transfer" size="lg" c-value="['stable']">
        <c-CTransferListItem value="alpha" label="Alpha channel" />
        <c-CTransferListItem value="beta" label="Beta channel" />
        <c-CTransferListItem value="stable" label="Stable channel" />
      </c-CTransferList>
    """
    css = """
      .brand-transfer {
        --cui-transfer-list-selected: color-mix(in srgb, MediumPurple 25%, Canvas);
        --cui-transfer-list-focus: MediumPurple;
        --cui-transfer-list-radius: 1rem;
      }
    """


preview = TransferListCustomization()
preview  # noqa: B018

size changes the default list height. Forced colors preserve selected-state outlines, reduced-motion environments disable component motion, and print hides action controls while retaining both supplied panes.

Scope boundaries

This first family owns a complete finite server-rendered collection. It does not fetch, filter, virtualize, group into a tree, expose read-only mode, or provide drag and drop. Use CMultiSelect for compact selection and compose application state with CVirtualWindow when the collection cannot be fully rendered.

API reference

Inputs

CTransferList server inputs

Server inputs are passed in a template through <c-CTransferList ... /> or in Python through CTransferList(...).

Input	Type	Default	Effect
`id`	`str \| None`	generated	Sets the root ID and bases stable listbox and option IDs.
`value`	`Sequence[str]`	`"()"`	Sets the ordered initial chosen values; every unique value must name one Item.
`name`	`str \| None`	`None`	Sets the repeated native form-entry name.
`form`	`str \| None`	`None`	Associates native and enhanced form values with an external Form ID.
`required`	`bool`	`False`	Requires at least one chosen value.
`disabled`	`bool`	`False`	Disables list selection controls and form contribution.
`show_move_all`	`bool`	`True`	Shows Add all and Remove all controls.
`show_reorder`	`bool`	`True`	Shows chosen-order controls.
`size`	`CTransferListSize` (`CTransferListSize`)	`"md"`	Selects compact default or spacious list height.
`available_label`	`str`	`"Available items"`	Overrides the localized available-pane title.
`chosen_label`	`str`	`"Chosen items"`	Overrides the localized chosen-pane title and native fallback label.
`available_empty_label`	`str`	`"No available items"`	Overrides the localized available empty state.
`chosen_empty_label`	`str`	`"No chosen items"`	Overrides the localized chosen empty state.
`count_label`	`str`	`"{selected} of {total} selected"`	Overrides pane counts and must retain both named placeholders.
`transfer_controls_label`	`str`	`"Transfer controls"`	Overrides the transfer toolbar accessible name.
`add_label`	`str`	`"Add selected"`	Overrides the Add selected action.
`add_all_label`	`str`	`"Add all"`	Overrides the Add all action.
`remove_label`	`str`	`"Remove selected"`	Overrides the Remove selected action.
`remove_all_label`	`str`	`"Remove all"`	Overrides the Remove all action.
`reorder_controls_label`	`str`	`"Chosen item order"`	Overrides the reorder toolbar accessible name.
`move_top_label`	`str`	`"Move to top"`	Overrides the Move to top action.
`move_up_label`	`str`	`"Move up"`	Overrides the Move up action.
`move_down_label`	`str`	`"Move down"`	Overrides the Move down action.
`move_bottom_label`	`str`	`"Move to bottom"`	Overrides the Move to bottom action.
`added_label`	`str`	`"{count} items added"`	Overrides multi-item Add announcements and must retain count.
`removed_label`	`str`	`"{count} items removed"`	Overrides multi-item Remove announcements and must retain count.
`reordered_label`	`str`	`"{count} items reordered"`	Overrides multi-item reorder announcements and must retain count.
`required_label`	`str`	`"Choose at least one item"`	Overrides the required-validation announcement.
`class_`	`CClassValue \| None` (`CClassValue`)	`None`	Adds classes to the root.
`style`	`CStyleValue \| None` (`CStyleValue`)	`None`	Adds root styles before owned theme variables.
`attrs`	`Mapping[str, object] \| None`	`None`	Adds copied allowed root attributes without replacing owned form semantics state or runtime markers.

CTransferList client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CTransferList />.

Input	Type	Omitted behavior	Effect
`value`	`string[] \| null`	Omission or null releases control to the committed value.	Controls the exact ordered chosen values while supplied.
`required`	`boolean`	Uses the server value.	Reactively changes required validity.
`disabled`	`boolean`	Uses the server and Fieldset state.	Reactively disables interaction and form contribution.
`onValueChange`	`function`	No component callback runs.	Receives transfer reorder and reset requests.

CTransferListItem server inputs

Server inputs are passed in a template through <c-CTransferListItem ... /> or in Python through CTransferListItem(...).

Input	Type	Default	Effect
`value`	`str`	required	Supplies nonempty unique stable identity and submitted value.
`label`	`str`	required	Supplies native fallback typeahead and accessible text.
`disabled`	`bool`	`False`	Prevents selection transfer and reorder while preserving an initial chosen value.
`class_`	`CClassValue \| None` (`CClassValue`)	`None`	Adds classes to the enhanced Option.
`style`	`CStyleValue \| None` (`CStyleValue`)	`None`	Adds styles to the enhanced Option.
`attrs`	`Mapping[str, object] \| None`	`None`	Adds copied allowed Option attributes without replacing owned semantics identity or state.

Slots

Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.

CTransferList slots

Slot	Required	Data	Fallback
`default`	no	`{}` (`CTransferListDefaultSlotData`)	Empty collection; accepts only CTransferListItem declarations.

CTransferListItem slots

Slot	Required	Data	Fallback
`default`	no	`{value, label, disabled, in_target, index}` (`CTransferListItemDefaultSlotData`)	Plain label text.

Events

Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.

CTransferList events

Event	Signature	Trigger and timing	Detail	Controlled and cancellation behavior
`onValueChange`	`(value: string[], detail: CTransferListChangeDetail) => void` (`CTransferListChangeDetail`)	A transfer reorder reset or accepted client reconciliation requests another ordered value.	`{value, previousValue, moved, source, controlled, sourceEvent}` (`CTransferListChangeDetail`)	Uncontrolled state commits and emits native input/change first; controlled state is request-only until accepted.

Methods

CSS

CSS variables to theme the components. Set them on an ancestor or the component itself.

CTransferList CSS variables

Apply these variables to CTransferList or one of its ancestors.

Variable	Type	Purpose	Default
`--cui-transfer-list-pane-size`	`length`	Native fallback and pane inline-size preference.	`15rem`
`--cui-transfer-list-list-size`	`length`	Enhanced listbox block size.	`sm 11rem; md 15rem; lg 20rem`
`--cui-transfer-list-gap`	`length`	Pane and control spacing.	`0.75rem`
`--cui-transfer-list-border`	`complete border value`	Pane control and Button borders.	`Adaptive 1px solid neutral`
`--cui-transfer-list-radius`	`length`	Pane and native fallback corners.	`0.625rem`
`--cui-transfer-list-surface`	`color`	Pane native fallback and Button surfaces.	`Canvas`
`--cui-transfer-list-selected`	`color`	Selected Option background.	`Adaptive blue`
`--cui-transfer-list-hover`	`color`	Hovered Option background.	`Adaptive neutral`
`--cui-transfer-list-focus`	`color`	Listbox and Button focus outline.	`Highlight`
`--cui-transfer-list-disabled-opacity`	`number`	Disabled root Option and Button opacity.	`0.55`

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CTransferList attributes

Attribute	Element	Type	Meaning
`role`	Available and chosen listbox divs	`listbox`	Exposes each enhanced pane as a selectable collection.
`aria-multiselectable`	Both listboxes	`true`	Declares independent multi-selection.
`aria-activedescendant`	Focused listbox	`IDREF \| absent`	Identifies the active Option while DOM focus remains on the listbox.
`role`	Enhanced Item div	`option`	Exposes one declared choice.
`aria-selected`	Enhanced Item div	`boolean-string`	Reflects ephemeral pane selection rather than chosen membership.
`aria-disabled`	Root listboxes and disabled Items	`boolean-string`	Reflects effective unavailability.
`aria-invalid`	Root	`true \| absent`	Marks a failed required validity check.
`data-value`	Enhanced Item div	`string`	Exposes stable identity.
`data-selected`	Enhanced Item div	`present \| absent`	Reflects ephemeral pane selection.
`data-disabled`	Root and disabled Items	`present \| absent`	Reflects effective unavailability.
`data-required`	Root	`present \| absent`	Reflects required validity.
`data-invalid`	Root	`present \| absent`	Reflects a failed native validity check.
`data-size`	Root	`CTransferListSize` (`CTransferListSize`)	Mirrors list-height profile.
`data-available-empty`	Root	`present \| absent`	Marks no available Items.
`data-chosen-empty`	Root	`present \| absent`	Marks no chosen Items.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CTransferList selectors

Selector	Element	Purpose
`[data-citry-ui-part="transfer-list"]`	Root div	State reflections attrs and theme destination.
`[data-citry-ui-part="native"]`	Native select multiple	Progressive fallback validity reset and initial form owner.
`[data-citry-ui-part="control"]`	Enhanced grid	Contains both panes and transfer controls.
`[data-citry-ui-part="pane"]`	Available or chosen section	Pane surface.
`[data-citry-ui-part="pane-header"]`	Pane header	Groups title and selection count.
`[data-citry-ui-part="pane-title"]`	Pane h3	Visible listbox label.
`[data-citry-ui-part="count"]`	Count span	Localized selected and total summary.
`[data-citry-ui-part="listbox"]`	Pane listbox div	Focus selection and Item-scroll owner.
`[data-citry-ui-part="option"]`	Item div	Rich presentation selection and stable Item customization.
`[data-citry-ui-part="empty"]`	Pane paragraph	Localized empty state.
`[data-citry-ui-part="transfer-controls"]`	Transfer toolbar	Add and Remove actions.
`[data-citry-ui-part="reorder-controls"]`	Reorder toolbar	Chosen-order actions.
`[data-citry-ui-part="button"]`	Native action Button	Transfer and reorder actions.
`[data-citry-ui-part="status"]`	Visually hidden polite live region	Accepted action and validation announcements.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

Interface	Definition
`CTransferListSize`	`Literal["sm", "md", "lg"]`
`CTransferListChangeSource`	`Literal["add", "add-all", "remove", "remove-all", "move-top", "move-up", "move-down", "move-bottom", "reset", "client"]`
`CClassValue`	`str \| Mapping[str, bool] \| Sequence[CClassValue]`
`CStyleValue`	`str \| Mapping[str, object] \| Sequence[CStyleValue]`

`CTransferListDefaultSlotData`

Empty dataclass: {}.

`CTransferListItemDefaultSlotData`

Field	Type	Default	Meaning
`value`	`str`	-	Stable declared Item value.
`label`	`str`	-	Plain accessible and typeahead label.
`disabled`	`bool`	-	Declared disabled state.
`in_target`	`bool`	-	Whether the Item is initially chosen.
`index`	`int`	-	Initial zero-based index in its pane.

`CTransferListChangeDetail`

Field	Type	Default	Meaning
`value`	`list[str]`	-	Requested or committed ordered chosen values.
`previousValue`	`list[str]`	-	Effective ordered chosen values before the request.
`moved`	`list[str]`	-	Values directly affected by the action in their action order.
`source`	`CTransferListChangeSource` (`CTransferListChangeSource`)	-	Transfer reorder reset or client cause.
`controlled`	`bool`	-	Whether client value currently owns chosen state.
`sourceEvent`	`object \| None`	-	Native source Event or null for client reconciliation.

Translation keys

Catalog keys used by this family. An explicit component input or slot listed in Override takes precedence over the catalog for that instance.

CTransferList translation keys

Key	Purpose	Variables	Override	Browser updates
`citry-ui-transfer-list-available`	Titles the available pane.	`None.`	`available_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-chosen`	Titles the chosen pane and native fallback.	`None.`	`chosen_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-available-empty`	Describes an empty available pane.	`None.`	`available_empty_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-chosen-empty`	Describes an empty chosen pane.	`None.`	`chosen_empty_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-count`	Summarizes selected and total Items in one pane.	`selected: str; total: str`	`count_label` with `{selected}` and `{total}`	Two `i18n.bind()` registrations update when selection totals or locale change.
`citry-ui-transfer-list-transfer-controls`	Names the transfer toolbar.	`None.`	`transfer_controls_label`	Stable `$c-tr` attribute follows client locale changes.
`citry-ui-transfer-list-add`	Labels the Add selected action.	`None.`	`add_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-add-all`	Labels the Add all action.	`None.`	`add_all_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-remove`	Labels the Remove selected action.	`None.`	`remove_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-remove-all`	Labels the Remove all action.	`None.`	`remove_all_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-reorder-controls`	Names the chosen-order toolbar.	`None.`	`reorder_controls_label`	Stable `$c-tr` attribute follows client locale changes.
`citry-ui-transfer-list-move-top`	Labels the Move to top action.	`None.`	`move_top_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-move-up`	Labels the Move up action.	`None.`	`move_up_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-move-down`	Labels the Move down action.	`None.`	`move_down_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-move-bottom`	Labels the Move to bottom action.	`None.`	`move_bottom_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-transfer-list-added-one`	Announces one accepted addition.	`None.`	`added_label` formats the fallback	One-shot `i18n.tr()` writes the live region.
`citry-ui-transfer-list-added`	Announces multiple accepted additions.	`count: str`	`added_label` with `{count}`	One-shot `i18n.tr()` writes the live region.
`citry-ui-transfer-list-removed-one`	Announces one accepted removal.	`None.`	`removed_label` formats the fallback	One-shot `i18n.tr()` writes the live region.
`citry-ui-transfer-list-removed`	Announces multiple accepted removals.	`count: str`	`removed_label` with `{count}`	One-shot `i18n.tr()` writes the live region.
`citry-ui-transfer-list-reordered-one`	Announces one accepted reorder.	`None.`	`reordered_label` formats the fallback	One-shot `i18n.tr()` writes the live region.
`citry-ui-transfer-list-reordered`	Announces multiple accepted reorders.	`count: str`	`reordered_label` with `{count}`	One-shot `i18n.tr()` writes the live region.
`citry-ui-transfer-list-required`	Announces failed required validity.	`None.`	`required_label`	One-shot `i18n.tr()` writes the live region.