chrome:shell.skip
chrome:nav.docs chrome:nav.cdk chrome:nav.components blocks:nav.blocks chrome:nav.tools chrome:nav.contribute chrome:nav.about
generated:catalog.area.docs
generated:catalog.entry.getting-started.title generated:catalog.entry.core.title generated:catalog.entry.styles.title generated:catalog.entry.themes.title generated:catalog.entry.forms-guide.title generated:catalog.entry.icons.title generated:catalog.entry.testing.title

generated:catalog.entry.core.title

@xngui/core
@xngui/core

generated:catalog.entry.core.description

docs:core.section.overview

docs:core.lead.overview

docs:core.heading.category-index

docs:core.paragraph.fourteen-categories

docs:core.data.visual

docs:core.data.semantic-variants-and-surface-treatments

types/visual.ts

docs:core.data.size

docs:core.data.control-scale-and-intrinsic-sizing-keywords

types/size.ts

docs:core.data.tokens

docs:core.data.primitive-steps-aligned-with-xngui-styles

types/tokens.ts

docs:core.data.layout

docs:core.data.flex-and-overlay-placement

types/layout.ts

docs:core.data.state

docs:core.data.contracts-and-feedback-status

types/state.ts

docs:core.data.interaction

docs:core.data.triggers-activation-scroll

types/interaction.ts

docs:core.data.capabilities

docs:core.data.signal-implements-contracts-for-components

types/capabilities.ts

docs:core.data.form

docs:core.data.options-validation-and-form-chrome

types/form.ts

docs:core.data.typography

docs:core.data.type-scale-and-text-treatment-unions

types/typography.ts

docs:core.data.events

docs:core.data.component-output-payloads

types/events.ts

docs:core.data.data

docs:core.data.headless-data-pipeline

types/data.ts

docs:core.data.media

docs:core.data.adornments-avatars-and-media-fit

types/media.ts

docs:core.data.runtime

docs:core.data.secondary-entry-points-for-app-bootstrap

config · i18n · errors · files · logging

docs:core.data.storage

docs:core.data.cross-package-storage-keys

storage/keys.ts

docs:core.heading.import-pattern

imports.ts
import type {  XVariant, XSize, XPlacement, XDataQuery, XChangeEvent, XOpenBound,} from '@xngui/core';import { X_STORAGE_KEYS } from '@xngui/core/storage';import { provideX } from '@xngui/core/config';

docs:core.section.visual

docs:core.heading.type-definitions

  • XVarianttype

    docs:core.data.component-variant-input

    primarysecondaryaccentdangersuccesswarninginfo
  • XColortype

    docs:core.data.palette-token-family-key

    primarysecondaryaccentneutralsuccesswarningdangerinfo
  • XAppearancetype

    docs:core.data.surface-treatment-for-controls

    solidoutlineghostsoft
  • XDensitytype

    docs:core.data.standard-baseline-roomier-comfortable-or-tighter-compact-chrome-spacing

    compactcomfortablestandard

docs:core.heading.variant-spectrum

docs:core.paragraph.xvariant-semantic-roles-for-actions-and-status-bearing-ui

primary
secondary
accent
danger
success
warning
info

docs:core.heading.appearance-gallery

docs:core.paragraph.xappearance-surface-treatments-paired-with-xvariant

solid
outline
ghost
soft

docs:core.heading.color-families

docs:core.paragraph.xcolor-includes-neutral-for-chrome-unlike-xvariant

primary--x-primary
secondary--x-secondary
accent--x-accent
neutral--x-neutral
success--x-success
warning--x-warning
danger--x-danger
info--x-info

docs:core.section.size

docs:core.heading.xsize-scale

docs:core.paragraph.five-steps-shared-across-buttons-inputs-chips-and-more

  • xsxs
  • smsm
  • mdmd
  • lglg
  • xlxl

docs:core.heading.xdensity-scale

docs:core.paragraph.xdensity-orthogonal-to-xsize docs:core.link.control-scale-styles.

XDensity · compact
XDensity · comfortable
XDensity · standard

docs:core.section.layout

docs:core.heading.layout-unions

docs:core.data.xorientation

horizontalvertical

docs:core.data.xalign

startcenterendstretchbaseline

docs:core.data.xjustify

startcenterendbetweenaroundevenly

docs:core.data.xposition

topbottomstartend

docs:core.data.xtextalign

startcenterendjustify

docs:core.data.xtextdirection

ltrrtl

docs:core.data.xoverlaylayer

dropdownstickyoverlaymodalfabtoast

docs:core.heading.placement-atlas

docs:core.paragraph.xplacement-twelve-anchored-positions-for-overlays-tooltips-and-menus

topbottomstartendtop-starttop-endbottom-startbottom-endstart-startstart-endend-startend-end

docs:core.heading.flex-samples

docs:core.paragraph.xorientation-xalign-xjustify-in-context

docs:core.data.horizontal-center-center
docs:core.data.horizontal-end-between
docs:core.data.vertical-stretch-start
docs:core.data.vertical-center-evenly

docs:core.heading.text-direction

docs:core.data.xtextdirection-ltr

docs:core.paragraph.logical-start-is-on-the-left-inline-flow-follows-reading-ord

docs:core.data.xtextdirection-rtl

docs:core.paragraph.logical-start-is-on-the-right-inline-flow-mirrors-for-rtl-lo

docs:core.section.state

docs:core.heading.contracts-unions

  • XDisabledinterface

    docs:core.data.disabled-boolean-contract

  • XLoadingModetype
    spinneroverlayreplace
  • XStatustype
    neutralinfosuccesswarningdanger
  • XVisibilitytype
    visiblehidden

docs:core.heading.status-spectrum

docs:core.heading.xstatus · neutral
docs:core.heading.xstatus · info
docs:core.heading.xstatus · success
docs:core.heading.xstatus · warning
docs:core.heading.xstatus · danger

docs:core.heading.state-contracts-in-context

XDisabled: false
XDisabled
XLoading

docs:core.section.interaction

docs:core.heading.interaction-types

docs:core.data.xtrigger

clickhoverfocusmanual

docs:core.data.xactivation

automaticmanual

docs:core.data.xselectionmode

singlemultiple

docs:core.data.xbuttontype

buttonsubmitreset

docs:core.data.xscrollstrategy

blocknoopclosereposition

docs:core.data.xfocusorigin

keyboardmousetouchprogram

docs:core.data.xarialive

offpoliteassertive

docs:core.section.form

docs:core.heading.form-types

docs:core.data.xlabelmode

staticfloatover

docs:core.data.xformlook

outlinefillflatnone

docs:core.data.xinputtype

textemailtelurl

docs:core.data.xvalidateon

dirtytoucheddirty-or-touchedsubmitalways

docs:core.data.xvalidationstate

neutralvalidinvalidpending

docs:core.section.events

docs:core.heading.typed-payloads

docs:core.paragraph.component-output-handlers-never-raw-event-unless-wrapped

  • XChangeEvent<T>{ value, previousValue? }
    event.ts
    { "value": "dark", "previousValue": "light" }
  • XClickEvent<T>{ originalEvent }
    event.ts
    { "originalEvent": "PointerEvent" }
  • XSelectionEvent<T>{ added, removed }
    event.ts
    { "added": ["a"], "removed": [] }
  • XPageEvent{ pageIndex, pageSize, length }
    event.ts
    { "pageIndex": 0, "pageSize": 25, "length": 120 }
  • XSortEvent{ sort }
    event.ts
    { "sort": { "active": "name", "direction": "asc" } }
  • XFocusEvent{ origin }
    event.ts
    { "origin": "keyboard" }
  • XBlurEvent{ originalEvent? }
    event.ts
    { "originalEvent": "FocusEvent" }

docs:core.section.data

docs:core.heading.pipeline

  1. docs:core.data.querydocs:core.data.xdataquery-page-sort-filter-snapshot
  2. docs:core.data.loaderdocs:core.data.xdataloader-t-sync-or-async-with-abortsignal
  3. docs:core.data.resultdocs:core.data.xdataresult-t-items-total-count
  4. docs:core.data.statusdocs:core.data.xdatastatus-idle-loading-success-error

docs:core.heading.shape-samples

docs:core.data.xdataquery

query.ts
{  "pageIndex": 0,  "pageSize": 25,  "sort": { "active": "name", "direction": "asc" },  "filter": null}

docs:core.data.xdataresult

result.ts
{  "items": ["Row A", "Row B", "Row C"],  "total": 120}

docs:core.heading.filter-table-types

docs:core.data.xsortdirection

ascdesc

docs:core.data.xdatastatus

idleloadingsuccesserror

docs:core.data.xfilterlogic

andor

docs:core.data.xselectionstate

nonesomeall

docs:core.data.xcolumnalign

startcenterend

docs:core.data.xemptystatetype

no-datano-resultserror
docs:core.data.xfilteroperator
eqneqgtgteltltecontainsstartsWithendsWithinnotInemptynotEmpty

docs:core.section.capabilities

docs:core.heading.signal-implements-contracts

docs:core.paragraph.components-opt-into-shared-behavior-with

  • XDisableableinterface

    docs:core.data.disabled-input-group-parents-may-pass-undefined-to-inherit

  • XLoadinginterface

    docs:core.data.loading-input-with-aria-busy-semantics

  • XOpenBoundinterface

    docs:core.data.declarative-overlays-dialog-drawer-alert-dialog

  • XAnchorBoundinterface

    docs:core.data.floating-surfaces-anchored-to-an-origin-menu-popover

  • XPaginatedinterface

    docs:core.data.page-index-size-with-navigation-helpers

  • XKeySelectioninterface

    docs:core.data.string-key-selection-for-tables-and-lists

  • XSortableinterface

    docs:core.data.column-sort-stack-for-data-tables

  • XToastHostinterface

    docs:core.data.imperative-toast-queue-api

  • XPlaybackinterface

    docs:core.data.native-audio-video-playback-controls

docs:core.section.tokens

docs:core.heading.css-typescript-bridge

docs:core.paragraph.css-typescript-bridge

  • XColor--x-{role}

    docs:core.bridge.xcolor-summary

    • docs:core.bridge.example.css-tokencolor: var(--x-primary);
    • docs:core.bridge.example.component-input<x-badge variant="danger" />
    • docs:core.bridge.example.tailwind-utility<div class="bg-primary text-primary-foreground">
  • XSize[data-size]

    docs:core.bridge.xsize-summary

    • docs:core.bridge.example.host-attribute<x-button />
    • docs:core.bridge.example.resolved-token--x-control-height: var(--x-size-height-lg);
    • docs:core.bridge.example.css-selectorx-input[data-size="md"] { … }
  • XDensity[data-density]

    docs:core.bridge.xdensity-summary

    • docs:core.bridge.example.host-attribute<x-button />
    • docs:core.bridge.example.resolved-token--x-control-pad-inline: calc(var(--x-scale-pad-inline) + var(--x-density-offset-pad-inline));
    • docs:core.bridge.example.config-defaultprovideX({ config: { density: 'comfortable' } })
  • XSemanticToken--x-{token}

    docs:core.bridge.xsemantictoken-summary

    • docs:core.bridge.example.page-canvasbackground: var(--x-background);
    • docs:core.bridge.example.elevated-surfacebackground: var(--x-card); border-color: var(--x-card-border);
    • docs:core.bridge.example.type-uniontype XSemanticToken = 'background' | 'card' | 'border' | …
  • XSpacingStep--x-spacing-{n}

    docs:core.bridge.xspacingstep-summary

    • docs:core.bridge.example.gapgap: var(--x-spacing-4);
    • docs:core.bridge.example.marginmargin-block: var(--x-spacing-6);
    • docs:core.bridge.example.component-input<x-stack gap="3" />
  • XRadiusStep--x-radius-{step}

    docs:core.bridge.xradiusstep-summary

    • docs:core.bridge.example.card-chromeborder-radius: var(--x-radius-lg);
    • docs:core.bridge.example.chip-badgeborder-radius: var(--x-radius-full);
    • docs:core.bridge.example.type-uniontype XRadiusStep = 'xs' | 'sm' | … | 'full'
  • XShadowStep--x-shadow-{step}

    docs:core.bridge.xshadowstep-summary

    • docs:core.bridge.example.popoverbox-shadow: var(--x-shadow-lg);
    • docs:core.bridge.example.component-input<x-card shadow="md" />
    • docs:core.bridge.example.type-uniontype XShadowStep = 'sm' | 'md' | 'lg' | 'xl' | '2xl'
  • XDurationStep--x-duration-{step}

    docs:core.bridge.xdurationstep-summary

    • docs:core.bridge.example.transitiontransition-duration: var(--x-duration-fast);
    • docs:core.bridge.example.animationanimation-duration: var(--x-duration-normal);
    • docs:core.bridge.example.type-uniontype XDurationStep = 'fast' | 'normal' | 'slow'
  • XOverlayLayer--x-z-{layer}

    docs:core.bridge.xoverlaylayer-summary

    • docs:core.bridge.example.dialogz-index: var(--x-z-modal);
    • docs:core.bridge.example.config-overrideprovideX({ config: { zIndex: { modal: 60 } } })
    • docs:core.bridge.example.type-uniontype XOverlayLayer = 'dropdown' | 'modal' | …
  • XTextSize--x-text-{size}

    docs:core.bridge.xtextsize-summary

    • docs:core.bridge.example.font-sizefont-size: var(--x-text-sm);
    • docs:core.bridge.example.paired-leadingline-height: var(--x-text-sm-leading);
    • docs:core.bridge.example.component<x-text>…</x-text>
  • XFontWeight--x-weight-{weight}

    docs:core.bridge.xfontweight-summary

    • docs:core.bridge.example.cssfont-weight: var(--x-weight-semibold);
    • docs:core.bridge.example.component<x-text weight="medium">…</x-text>
    • docs:core.bridge.example.type-uniontype XFontWeight = 'normal' | 'medium' | 'bold' | …

docs:core.heading.primitive-steps

docs:core.paragraph.align-with-xngui-styles-primitives

docs:core.data.xspacingstep

012…96

docs:core.data.xradiusstep

nonexssmmdlgxl2xlfull

docs:core.data.xshadowstep

smmdlgxl2xl

docs:core.data.xdurationstep

fastnormalslow

docs:core.data.xsemantictoken

backgroundforegroundcardringselected…

docs:core.section.typography

docs:core.heading.type-scale-treatment

docs:core.data.xtextsize

2xsxssmmdlgxl2xl3xl4xl5xl6xl7xl8xl9xl

docs:core.data.xfontweight

thinextralightlightnormalmediumsemiboldboldextraboldblack

docs:core.data.xtexttransform

noneuppercaselowercasecapitalize

docs:core.data.xtextoverflow

clipellipsis

docs:core.section.translation

docs:core.lead.translation

docs:core.heading.translation-pipeline

  • docs:core.i18n.pipeline.bootstrap

  • docs:core.i18n.pipeline.locale

  • docs:core.i18n.pipeline.loader

  • docs:core.i18n.pipeline.merge

  • docs:core.i18n.pipeline.resolve

docs:core.heading.translation-overview

docs:core.paragraph.translation-overview

docs:core.paragraph.translation-bootstrap

app.config.ts
import { provideX } from '@xngui/core/config';import { provideXTranslations } from '@xngui/core/i18n';export const appConfig = {  providers: [    provideX({      i18n: {        languages: ['en', 'fa', 'ar'],        defaultLocale: 'en',        fallbackLocale: 'en',      },    }),    provideXTranslations({      'app.title': { en: 'My app' },    }),  ],};
app.config.ts
import { provideX } from '@xngui/core/config';import { provideXTranslations } from '@xngui/core/i18n';// Lazy JSON — component catalogs (@xngui/i18n) via provideX i18nprovideX({  i18n: {    languages: ['en', 'fa'],    defaultLocale: 'en',    fallbackLocale: 'en',  },});// Eager TS — app-only keys (bundled)provideXTranslations({ 'footer.tagline': { en: 'Ship faster.' } });

docs:core.heading.translation-api

  • @xngui/core/i18n

    docs:core.data.lazy-json-loader-locale-persistence-intl

    provideX i18ncreateFetchI18nLoaderresolveI18nAssetPathXLocaleServiceXTranslationServiceXIntlServiceXTranslatePipemergeLocaleJsonprovideXTranslations
  • @xngui/i18n

    docs:core.data.component-translation-json-catalogs

    locales/en.jsonlocales/fa.json…

docs:core.section.runtime

docs:core.heading.app-bootstrap

docs:core.paragraph.providex-from-xngui-core-config-registers

app.config.ts
import { provideX } from '@xngui/core/config';export const appConfig = {  providers: [    provideX({      config: { size: 'sm', validateOn: 'touched' },      i18n: {        languages: ['en-US', 'en', 'fa'],        defaultLocale: 'en-US',        fallbackLocale: 'en',      },    }),  ],};

docs:core.heading.xconfig-defaults

docs:core.paragraph.override-once-via

size
mdXSize
density
standardXDensity
variant
primaryXVariant
appearance
outlineXAppearance
labelMode
staticXLabelMode
look
outlineXFormLook
validateOn
touchedXValidateOn
ripple
trueboolean
animate
trueboolean
overlay.placement
bottom-startXPlacement
overlay.closeOnEscape
trueboolean
overlay.closeOnOutside
trueboolean
overlay.closeOnBackdrop
trueboolean

docs:core.heading.secondary-entry-points

  • @xngui/core/config

    docs:core.data.library-wide-defaults-size-density-validateon-z-index-layers

    provideXprovideXConfigXConfigServiceXConfig
  • @xngui/core/direction

    docs:core.data.runtime-ltr-rtl-with-persisted-preference

    XDirectionService
  • @xngui/core/errors

    docs:core.data.domain-errors-and-a-pluggable-global-handler

    provideXErrorHandlerXErrorHandlerServiceXComponentError
  • @xngui/core/files

    docs:core.data.pick-extract-validate-read-and-download-browser-files

    XFileServiceXBrowserFileServicevalidateFilesdownloadTextpickFiles
  • @xngui/core/logging

    docs:core.data.structured-logging-with-injectable-backends

    provideXLoggerXLoggerServiceXLogger
  • @xngui/core/storage

    docs:core.data.ssr-safe-localstorage-indexeddb-and-shared-keys

    XLocalStorageServiceXIndexedDbServiceX_STORAGE_KEYS

docs:core.section.storage

docs:core.paragraph.storage-services

docs:core.heading.storage-services

docs:core.data.storage-theme
x-theme
docs:core.data.storage-theme-palette
x-theme-palette
docs:core.data.storage-locale
x-locale
docs:core.data.storage-direction
x-direction
docs:core.data.x-storage-keys
x-config

docs:core.section.media

docs:core.heading.adornments-avatars

docs:core.data.xiconposition

start
end

docs:core.data.xavatarshape

circle
square
rounded