CngxSelectShell
projects/forms/select/select-shell/select-shell.component.ts
Import#
import { CngxSelectShell } from '@cngx/forms/select'
Description#
Native-feeling single-value dropdown with declarative options -
consumers project <cngx-option> / <cngx-optgroup> children and
the shell derives a hierarchy-aware option model.
Bridges the raw-listbox compose-yourself path and the data-mode
<cngx-select [options]> path: same family-level intelligence
(reactive trigger ARIA, panel composition, template-slot cascade)
applied to a content-projected option list.
Naming: distinct from the internal CngxSelectPanelShell -
Shell here is the projection-shell that wraps consumer option
markup.
Metadata#
Host#
Providers#
CNGX_FORM_FIELD_CONTROL- useExisting
CngxSelectShell CNGX_STATEFUL- useFactory
(): { readonly state: CngxAsyncState} => { const self = inject(CngxSelectShell); return { state: self.commitState }; } CNGX_SELECT_PANEL_HOST- useExisting
CngxSelectShell CNGX_SELECT_PANEL_VIEW_HOST- useExisting
CngxSelectShell CNGX_OPTION_STATUS_HOST- useExisting
CngxSelectShell CNGX_OPTION_FILTER_HOST- useExisting
CngxSelectShell CNGX_OPTION_INTERACTION_HOST- useExisting
CngxSelectShell CNGX_SELECT_SHELL_SEARCH_HOST- useExisting
CngxSelectShell
Dependencies#
CNGX_TEMPLATE_REGISTRY_FACTORYinject()tplRelationships
Depends on15
Index#
Properties
Inputs
Outputs
HostBindings
Inputs#
TemplateRef | null nullTemplateRef | null nullCngxSelectCommitAction | null nullCngxCommitErrorAnnouncePolicyScalar-commit error-announce policy. Per-instance input wins over
CngxSelectConfig.commitErrorAnnouncePolicy. Default
{ kind: 'verbose', severity: 'assertive' }.
this.config.commitErrorAnnouncePolicy ?? { kind: 'verbose', severity: 'assertive' }, CngxSelectCompareFn cngxSelectDefaultCompare as CngxSelectCompareFn<T>, Debounce for searchTermChange (ms). Forward-compatible input -
the shipped CNGX_SEARCH_EFFECTS_FACTORY emits immediately;
consumers overriding the factory read this signal to size their
pipeline.
this.config.typeaheadDebounceIntervalTwo-way bindable search term. Drives per-option visibility through
CngxOptionFilterHost and filters the listbox AD so keyboard nav
skips hidden options. Empty string disables the filter.
''nullOutputs#
unknownTwo-way bindable search term. Drives per-option visibility through
CngxOptionFilterHost and filters the listbox AD so keyboard nav
skips hidden options. Empty string disables the filter.
Live search term emitted via CNGX_SEARCH_EFFECTS_FACTORY. The
factory's skipInitial gate suppresses the seed '' emission so
server-driven autocomplete consumers don't fire a blank search.
CngxSelectShellChangeAsyncStatusInstance Properties#
unknownthis.core.bindCommitRetry(() =>
this.scalarHandler.retryLast(),
)unknowncomputed<(a: unknown, b: unknown) => boolean>(
() => this.compareWith() as unknown as (a: unknown, b: unknown) => boolean,
)unknownthis.core.resolvedSelectionIndicatorPositionunknownthis.core.resolvedSelectionIndicatorVariantunknownPer-instance match policy. Receives (value, label, term) and
returns true when the option should stay visible. Default:
case-insensitive substring on the label.
input<((value: T, label: string, term: string) => boolean) | null>(null)unknownCurrently selected option resolved against the derived option model.
computed<CngxSelectOptionDef<T> | null>(() => this.selectedOption(), {
equal: (a, b) => {
if (a === b) {
return true;
}
if (a === null || b === null) {
return false;
}
return (this.compareWith() as CngxSelectCompareFn<unknown>)(a.value, b.value);
},
})unknownVariant-specific trigger-label slot. Inline because the directive's typed context shape varies per variant.
computed<TemplateRef<
CngxSelectTriggerLabelContext<T>
> | null>(() => this.triggerLabelDirective()?.templateRef ?? null)Methods#
HostBindings#
| Binding | Expression |
|---|---|
[id] | resolvedId() |
[attr.aria-readonly] | ariaReadonly() |
Structural styles shared across the entire CngxSelect family -
imported via styleUrls from every variant (CngxSelect,
CngxMultiSelect, CngxCombobox, CngxTypeahead, CngxTreeSelect,
CngxReorderableMultiSelect, CngxActionSelect,
CngxActionMultiSelect, CngxSelectShell, and the panel components).
All variants run encapsulation: None so the rules below are global;
the .cngx-select__* BEM-style class prefix is the namespace.
State modifiers
.cngx-option--highlightedon an option row - primary-tinted background marking the keyboard-focused row[aria-disabled='true']on an option - opacity 0.5 +cursor: not-allowed.cngx-select__option--pending-cursor: progresswhile a row's commit is in flight.cngx-select__chip-list--reordering- whole-stripcursor: grabbingwhile a drag is active.cngx-select__chip--draggingon a chip - Trello-style lift (shadow + scale + tilt + accent fill).cngx-select__chip--drag-overon a chip - vertical drop bar painted on the leading edge via::before
Variants
Chip-list overflow modes via data-overflow:
- default - flex-wrap chips across multiple rows
data-overflow='scroll-x'- single row + horizontal scrolldata-overflow='truncate'- single row + clipped overflow + the.cngx-select__chip-overflow-badgecount pill
Error surfaces with two layouts:
.cngx-select__error- column-stacked block (message + retry).cngx-select__error--inline- inline banner above the option list.cngx-select__commit-error- per-commit failure banner
Slots
.cngx-select__panel- the floating panel surface (anchor-positioned viaposition-try-fallbacks).cngx-select__group-header- uppercase optgroup label.cngx-select__option/.cngx-select__check- option row + the selected-state checkmark.cngx-select__loading/.cngx-select__empty- inline message rows.cngx-select__skeleton/.cngx-select__skeleton-row- first-load shimmer placeholders (static underprefers-reduced-motion).cngx-select__spinner-wrap/.cngx-select__spinner- first-load spinner ring.cngx-select__loading-bar- first-load top-edge progress bar.cngx-select__refreshing/.cngx-select__refreshing-spinner/.cngx-select__refreshing-dots- subsequent-load indicators.cngx-select__option-spinner/.cngx-select__option-error- per-row commit feedback.cngx-select__chip-list/.cngx-select__chip-overflow-badge- chip strip + overflow count.cngx-select__chip-wrap/.cngx-select__chip-handle- reorderable chip surface + optional drag-handle glyph.cngx-select__error/.cngx-select__error--inline/.cngx-select__error-message/.cngx-select__error-retry/.cngx-select__commit-error- error block, banner, and retry pieces
Inheritance
Tokens are registered top-level in @layer cngx.tokens via @property
so any consumer (cngx.theme layer, app layer) can override without
learning the type.
Panel surface, every primary-tinted glyph, and every danger-toned error surface delegate to the foundation so a dark-mode swap cascades through the floating panel even when anchor positioning detaches it from the trigger's DOM context:
--cngx-select-panel-border->--cngx-color-border--cngx-select-panel-bg->--cngx-color-surface--cngx-select-panel-color->--cngx-color-text--cngx-select-panel-shadow->--cngx-shadow-md--cngx-select-check-color->--cngx-color-primary--cngx-select-spinner-color->--cngx-color-primary--cngx-select-loading-bar-color->--cngx-color-primary--cngx-select-refreshing-color->--cngx-color-primary--cngx-select-option-spinner-color->--cngx-color-primary--cngx-select-option-error-color->--cngx-color-danger--cngx-select-error-color->--cngx-color-danger--cngx-select-chip-remove-hover-color->--cngx-color-danger--cngx-select-chip-drag-bg->--cngx-color-primary--cngx-select-chip-drop-bar-color->--cngx-color-primary--cngx-select-trigger-invalid-border-color->--cngx-color-danger--cngx-select-trigger-invalid-outline-color->--cngx-color-danger
--cngx-select-panel-min-width is intentionally NOT registered via
@property so the anchor-size(width) fallback survives when the
consumer doesn't override it; registering it with any initial-value
would shadow the var() fallback and break anchor positioning.
Dark mode
Three hooks swap alpha-on-black surfaces (panel shadow, option highlight, spinner track, chip-overflow tint, chip remove-hover tint, chip handle muted, chip drag shadow) plus the skeleton shimmer gradient and the option-spinner track:
prefers-color-scheme: dark[data-color-scheme="dark"].darkclass
Foundation-delegated tokens ride the foundation cascade unchanged.
Pair with
@cngx/themes/material/select-theme- Material 3 surface treatment across the entire family
Trigger skin for CngxSelectShell - the declarative-projection
counterpart to CngxSelect (consumers project <cngx-option> /
<cngx-optgroup> / <cngx-select-divider> instead of binding to a
data source). The host carries .cngx-select-shell; surface mirrors
single-select/select.component.css but namespaces every tunable
through --cngx-select-shell-* so the declarative variant can be
themed independently of the data-mode CngxSelect. Structural rules
(panel frame, option rows, async-state surfaces) ride on
shared/select-base.css.
State modifiers
:focus-visibleon.cngx-select-shell__trigger- focus-ring outline + offset[aria-disabled='true']on the trigger - opacity dim +cursor: not-allowed:hoveron.cngx-select-shell__clear- opacity 1:focus-visibleon the clear button - 2px primary-tinted outline
Slots
.cngx-select-shell__root-display: contentshost shim.cngx-select-shell__trigger- the bordered row (user-select: noneprevents drag-click text selection).cngx-select-shell__label- ellipsis-truncating value summary (inline-flex with--label-gapbetween glyph and text).cngx-select-shell__caret- panel-state glyph.cngx-select-shell__clear- reset button
Inheritance
Trigger tokens delegate up the family chain so consumer themes can override at the level they want to brand:
--cngx-select-shell-*->--cngx-select-*-> hardcoded--cngx-select-shell-border->--cngx-color-border--cngx-select-shell-focus-outline->--cngx-color-primary--cngx-select-shell-focus-ring->--cngx-color-primary
Once registered via @property the inner var() steps are
documentation-only; system tokens (--cngx-color-*) are the
brand-wide override path.
Pair with
@cngx/themes/material/select-theme- Material 3 surface treatment shared across the entire select family
Index#
Surface
Layout
State / Highlighted
State / Selected
State / Loading
State / Refreshing
State / Commit
State / Remove
State / Dragging
State / Error
State / Trigger invalid
State / Clear
Surface
*1px solid oklch(0.85 0.01 250)Border shorthand of the dropdown panel. Falls back through
--cngx-color-border. inherits: true so the :root delegating
value reaches the floating panel host (anchor-positioned, may
sit outside the normal DOM flow).
See: [[--cngx-color-border]]
<color>oklch(1 0 0)Background of the dropdown panel. Falls back through
--cngx-color-surface.
See: [[--cngx-color-surface]]
*currentColorText color inside the panel. syntax: '*' + initial-value
currentColor lets the panel inherit text color from its
ancestor by default. Registering as <color> would forbid
currentColor since <color> requires a computationally-
independent value.
*0 4px 12px oklch(0 0 0 / 0.12)Drop-shadow shorthand. Falls back through --cngx-shadow-md.
inherits: true so the :root dark-mode override (deeper shadow
on dark) reaches the floating panel host.
<color>oklch(0 0 0 / 0.5)Color of the placeholder text shown when no value is selected.
<color>oklch(0 0 0 / 0.5)Color of the dropdown caret glyph shared across every variant.
Muted by default to mirror the placeholder token; the Material
bridge maps it to --mat-sys-on-surface-variant. inherits: true
so a trigger-level override reaches the glyph element.
<color>oklch(0 0 0 / 0.5)Color of the clear-button glyph shared across every variant. Tracks
the same muted default as the caret so both trigger affordances read
uniformly. inherits: true so a trigger-level override reaches the
glyph element.
*1px solid oklch(0.85 0.01 250)Border shorthand of the trigger.
Layout
*16remMaximum height before vertical scrolling kicks in.
*autoMinimum height of an option row - defaults to auto so dense
rows stay compact.
*1.25emFont-size of the dropdown caret glyph shared across every variant.
*0.25remCorner radius of the reorderable chip wrap container.
*0.25remGap between the chip body and any projected drag handle.
*2.25remMinimum block size of the trigger. Shared family default so the shell trigger matches the other variants instead of sizing to content.
*0.375remGap inside the label slot (between glyph and text).
State / Highlighted
<color>oklch(0.66 0.19 50 / 0.1)Background of the keyboard-highlighted option row. Defaults to a
low-alpha tint of --cngx-color-primary so the highlight reads
as brand-accented without competing with selection state.
See: [[--cngx-color-primary]]
State / Selected
<color>oklch(0.66 0.19 50)Color of the selected-option checkmark glyph. Falls back through
--cngx-color-primary.
See: [[--cngx-color-primary]]
State / Disabled
<number>0.5Opacity multiplier applied when the trigger is disabled. Shared family-wide so every variant dims its disabled trigger identically.
<number>0.5Opacity multiplier applied when the trigger is disabled.
State / Loading
*0.125remCorner radius of each skeleton placeholder row.
*2px solid oklch(0 0 0 / 0.15)Track stroke of the first-load spinner ring. inherits: true
so the :root dark-mode override (alpha-on-white on dark)
reaches the spinner inside the floating panel.
<color>oklch(0.66 0.19 50)Indicator stroke of the first-load spinner ring. Falls back to
--cngx-color-primary.
<color>oklch(0.66 0.19 50)Color of the first-load loading bar. Falls back to
--cngx-color-primary.
State / Refreshing
<length>2pxHeight of the subsequent-load refreshing bar.
<color>oklch(0.66 0.19 50)Color of the refreshing bar gradient. Falls back to
--cngx-color-primary.
*0.25remPadding around the refreshing spinner wrapper.
*0.375remPadding around the refreshing dots block.
State / Commit
<color>oklch(0.66 0.19 50)Indicator stroke of the per-row commit spinner.
<color>oklch(0.6 0.18 25)Glyph color of the per-row commit error indicator. Falls back to
--cngx-color-danger.
*0.375rem 0.5remPadding of the commit error banner.
State / Overflow
<color>oklch(0 0 0 / 0.08)Background of the chip overflow badge shown in truncate overflow mode.
<color>oklch(0 0 0 / 0.6)Text color of the chip overflow badge.
State / Remove
*1.25remHit-target diameter of the chip remove button inside a reorderable chip wrap.
<color>oklch(0 0 0 / 0.12)Background tint of the chip remove button on hover.
<color>oklch(0.6 0.18 25)Foreground color of the chip remove button on hover. Falls back
to --cngx-color-danger.
State / Reorder
<color>oklch(0.5 0.01 250)Color of the optional projected drag-handle glyph.
*0.75remFont-size of the optional projected drag-handle glyph.
State / Dragging
*0 8px 20px oklch(0 0 0 / 0.28)Drop-shadow of the chip lifted into the dragging state.
inherits: true so the :root dark-mode override (deeper shadow
on dark) reaches the chip while it's being dragged.
<color>oklch(0.66 0.19 50)Background of the chip lifted into the dragging state. Falls back
to --cngx-color-primary.
See: [[--cngx-color-primary]]
<color>oklch(1 0 0)Text color of the chip lifted into the dragging state.
<number>1.06Scale multiplier of the dragging chip - Trello-style lift.
<angle>-1.5degRotation tilt applied to the dragging chip - Trello-style lift.
<length>3pxWidth of the drop-indicator bar between chips.
<color>oklch(0.66 0.19 50)Color of the drop-indicator bar between chips. Falls back to
--cngx-color-primary.
State / Error
<color>oklch(0.6 0.18 25)Text color of every error surface. Falls back to
--cngx-color-danger.
See: [[--cngx-color-danger]]
*0.375rem 0.5remPadding of the inline error banner shown above the option list.
*1px solid currentColorBorder shorthand of the error retry button.
State / Trigger invalid
<color>oklch(0.6 0.18 25)Border color painted on the trigger wrapper when aria-invalid="true".
Defaults track --cngx-color-danger via the delegating :root entry below.
<length>1pxBorder width painted on the trigger wrapper when aria-invalid="true".
<color>oklch(0.6 0.18 25)Outline color layered on the invalid trigger when focus is inside it.
Defaults track --cngx-color-danger via the delegating :root entry below.
*0 0 0 3px oklch(0.6 0.18 25 / 0.2)Soft halo layered behind the invalid trigger at focus time. Authored as a
box-shadow so it composes with any consumer-supplied focus outline.
State / Focus
*2px solid oklch(0.66 0.19 50)Focus-ring outline shorthand. Falls back to --cngx-color-primary.
See: [[--cngx-color-primary]]
<color>oklch(0.66 0.19 50)Focus-ring color used on the clear button's focus state.
State / Clear
Material theme
import { ChangeDetectionStrategy, Component, ViewEncapsulation, signal } from '@angular/core';
import { CngxSelectShell, CngxSelectOption } from '@cngx/forms/select';
/**
* `CngxSelectShell` rendered against a Material 3 palette via the published
* `@cngx/themes/material/select-theme` bridge.
*
* The stylesheet builds a real M3 theme: `mat.theme` emits the `--mat-sys-*`
* system tokens, then `select.theme($theme)` routes every `--cngx-select-*`
* token onto its Material counterpart, so the trigger, panel surface, and
* selected-option tones inherit the palette with no per-instance overrides.
* `ViewEncapsulation.None` lets the global `html` theme and the
* `:where(cngx-select-shell)` bridge rules reach both the trigger and the
* top-layer panel.
*/
@Component({
selector: 'app-root',
standalone: true,
changeDetection: ChangeDetectionStrategy.OnPush,
encapsulation: ViewEncapsulation.None,
imports: [CngxSelectShell, CngxSelectOption],
styleUrl: './material-theme.component.scss',
template: `
<div class="demo">
<cngx-select-shell
[label]="'Favorite color'"
[(value)]="value"
[selectionIndicatorPosition]="'after'"
placeholder="Pick a color…"
>
<cngx-option [value]="'red'">Red</cngx-option>
<cngx-option [value]="'green'">Green</cngx-option>
<cngx-option [value]="'blue'">Blue</cngx-option>
<cngx-option [value]="'amber'">Amber</cngx-option>
<cngx-option [value]="'violet'">Violet</cngx-option>
</cngx-select-shell>
<p class="demo__readout">Selected: {{ value() ?? '—' }}</p>
</div>
`,
})
export class MaterialThemeExample {
protected readonly value = signal<string | undefined>(undefined);
}
export { MaterialThemeExample as AppComponent };