GET STARTED

Configuration

Configure NeuralNg once, then control direction, density and color mode through small Signal-based runtime services.

Environment providersRuntime SignalsSSR safe

APPLICATION SETUP

Register the environment providers

provideNeuralNg() owns shared component preferences and the initial locale. provideNeuralAppearance() is the optional application controller for palettes, mode, direction, persistence and the root DOM contract.

import { ApplicationConfig } from '@angular/core';
import { provideNeuralNg } from '@neural-ng/core';
import { provideNeuralAppearance } from '@neural-ng/core/appearance';
import { neuralTr } from '@neural-ng/core/locales/tr';

export const appConfig: ApplicationConfig = {
  providers: [
    provideNeuralNg({
      locale: neuralTr,
      direction: 'auto',
      density: 'comfortable',
      unstyled: false,
    }),
    provideNeuralAppearance({
      primary: 'violet',
      surface: 'slate',
      mode: 'system',
      direction: 'auto',
      storageKey: 'product-appearance',
    }),
  ],
};

Defaults and accepted values

Every option is optional. Unknown palettes and invalid direction, density or color-mode values fail immediately instead of silently producing mixed state.

OptionDefaultAccepted values

unstyledfalsetrue | false

directionautoauto | ltr | rtl

densitycomfortablecompact | comfortable | spacious

localeEnglishNeuralLocale

primaryblueregistered palette name

surfaceslateregistered palette name

modesystemlight | dark | system

storageKeyneural-appearancestring prefix | null

Live configuration

These controls update the same root-level contracts used by every component on this documentation site.

Direction

Density

Configured direction: ltr
Resolved direction: ltr
Density: comfortable

Runtime direction and density

direction(), resolvedDirection() and density() are readonly Signals. When direction is auto, the active locale supplies the resolved direction. reset() restores the provider values.

import { Component, inject } from '@angular/core';
import { NeuralNgService } from '@neural-ng/core';

@Component({
  selector: 'app-preferences',
  template: `
    <output>
      {{ neural.direction() }} /
      {{ neural.resolvedDirection() }} /
      {{ neural.density() }}
    </output>
  `,
})
export class Preferences {
  readonly neural = inject(NeuralNgService);

  useCompactRtl(): void {
    this.neural.setDirection('rtl');
    this.neural.setDensity('compact');
  }

  reset(): void {
    this.neural.reset();
  }
}

One reactive appearance controller

primary(), surface(), mode(), resolvedMode() and direction are readonly Signals. Commands update the complete palette, namespaced DOM attributes and persisted preferences together.

import { Component, inject } from '@angular/core';
import { NeuralAppearanceService } from '@neural-ng/core/appearance';

@Component({
  selector: 'app-appearance-picker',
  template: `
    <neural-button label="Violet" (clicked)="appearance.setPrimary('violet')" />
    <neural-button label="Dark" (clicked)="appearance.setMode('dark')" />
    <neural-button label="RTL" (clicked)="appearance.setDirection('rtl')" />
    <output>
      {{ appearance.primary() }} /
      {{ appearance.surface() }} /
      {{ appearance.resolvedMode() }}
    </output>
  `,
})
export class AppearancePicker {
  readonly appearance = inject(NeuralAppearanceService);
}

Set storageKey: null when persistence is not wanted. Appearance already configures color mode; do not also register provideNeuralColorMode().

The root DOM contract

NeuralNg uses namespaced data attributes and the native dir attribute. Theme identity and resolved color mode are deliberately separate concerns. Primary and surface names identify the active registered scales.

<html
  dir="rtl"
  data-neural-direction="rtl"
  data-neural-density="compact"
  data-neural-mode="dark"
  data-neural-primary="violet"
  data-neural-surface="slate"
  data-neural-theme="neutral"
>
  ...
</html>

Global headless mode

Global unstyled removes NeuralNg visual classes from all participating components. Native semantics, interaction, ARIA, structural hooks and typed consumer class slots remain.

import { ApplicationConfig } from '@angular/core';
import { provideNeuralNg } from '@neural-ng/core';

export const appConfig: ApplicationConfig = {
  providers: [provideNeuralNg({ unstyled: true })],
};

SSR and hydration rules

Use the same initial locale

Configure identical locale and direction inputs on server and browser. Do not infer locale during component rendering.

Plan first-paint mode

The server cannot read local storage or media queries. Use an application-owned CSP-compatible head script when persisted mode must apply before paint.