Skip to main content
cngx-src documentation

CngxSort

DirectivePrimaryv0.1.0

projects/common/data/sort/sort.directive.ts

GitHub

Import#

import { CngxSort } from '@cngx/common/data'

Description#

Atom directive that tracks sort state (active field + direction).

Supports both uncontrolled (internal state) and controlled modes. In controlled mode the cngxSortActive / cngxSortDirection inputs take precedence over the internal state - pair with sortChange to keep them in sync.

An uncontrolled sort may declare a starting column + direction via [cngxSortInitial]: it seeds the internal state exactly once on init, then user clicks take over. Distinct from the controlled cngxSortActive / cngxSortDirection pins - the seed is skipped when a controlled pin is bound.

When multiSort is true, holding Shift while clicking a sort header adds it as a secondary (tertiary, …) sort key instead of replacing the primary one. Shift-clicking an active column cycles it asc → desc → removed. Multi-sort state is always uncontrolled; use sortsChange to read it. While a controlled pin is bound, additive clicks degrade to the single-sort cycle.

Consumer connects this to a table or list via a computed() - nothing is injected automatically.

https://cngxjs.github.io/cngx/examples/#/common/data/sort/basic https://cngxjs.github.io/cngx/examples/#/common/data/sort/multi-sort https://cngxjs.github.io/cngx/examples/#/common/data/sort/controlled https://cngxjs.github.io/cngx/examples/#/common/data/sort/aria-and-keyboard

Related#

Metadata#

Selector
[cngxSort]
Export as
cngxSort

Index#

Methods

clearsetSort

Inputs

activeInputdirectionInputinitialSortmultiSort

Outputs

sortChangesortsChange

Derived State

activedirectionisActivesortsorts

Inputs#

activeInput#string | undefined
input()

Controlled active column. When bound, takes precedence over internal state (single-sort only).

default undefined, { alias: 'cngxSortActive' }
directionInput#'asc' | 'desc' | undefined
input()

Controlled direction. When bound, takes precedence over internal state (single-sort only).

default undefined, { alias: 'cngxSortDirection', }
initialSort#SortEntry | undefined
input()

Uncontrolled starting sort. Seeds the internal state once on init if no sort is set yet and no controlled cngxSortActive pin is bound; user clicks own it thereafter. Ignored in controlled mode.

default undefined, { alias: 'cngxSortInitial' }
multiSort#boolean
input()

When true, Shift+click on a sort header adds it to the sort stack instead of replacing the current sort.

default false

Outputs#

sortChange#SortEntry | undefined
output()

Emitted when the primary sort state changes. Emits undefined on clear.

sortsChange#SortEntry[]
output()

Emitted whenever the sort stack changes (including removals and full clears). Always reflects the full sorts array at the time of emission.

Methods#

clear#void

Clears all active sorts. Emits both sortChange(undefined) and sortsChange([]).

setSort#void
setSort(field: string, additive: unknown)

Sets or toggles the sort for field.

additive = false (default, plain click):

  • Same field → cycle asc → desc → cleared (a third click removes the sort)
  • Different field → replace stack with { field, asc }

additive = true (Shift+click when multiSort is enabled on the header):

  • Field not in stack → append as asc
  • Field in stack as asc → change to desc
  • Field in stack as desc → remove from stack

With a controlled cngxSortActive pin bound, the sort is event-only: the cycle is computed off the effective entry and emitted, the internal state stays untouched (nothing stale surfaces if the pin unbinds later). Since multi-sort is always uncontrolled, an additive call degrades to the non-additive controlled cycle while a pin is bound.

@paramfieldstring
@paramadditiveunknown= false
Enter to selectArrow Down Arrow Up to navigateEsc to close