Troubleshooting

START HERE

Identify which layer is failing

Angular does not recognize the component

Import the public symbol from its component entry point and add it to the standalone host's imports. Do not guess a root-barrel name or import an implementation file.

import { NeuralSelect } from '@neural-ng/core/select';

@Component({
  imports: [NeuralSelect],
  template: `<neural-select [options]="cities" />`,
})
export class ShippingForm {}

An icon appears as a square or empty box

The class exists in markup but its mask rule is absent from the loaded CSS. The curated stylesheet covers common application icons; less common icons require their category or the complete catalog.

/* Always include the icon base and curated set */
@import '@neural-ng/icons/icons.css';

/* If an icon is not curated, add its category */
@import '@neural-ng/icons/categories/development.css';

/* Complete catalog: largest option */
/* @import '@neural-ng/icons/all.css'; */

Also confirm both classes are present: nt nt-icon-name. Neural Icons are local package assets and do not require a network request.

Components stay white, dark mode fails or primary does not change

Load the Neutral theme globally before application overrides. Tailwind users also load the bridge and bind the dark variant to data-neural-mode. Confirm that global unstyled was not enabled unintentionally.

@import 'tailwindcss';
@import '@neural-ng/core/themes/neutral.css';
@import '@neural-ng/core/themes/tailwind.css';
@import '@neural-ng/icons/icons.css';

@custom-variant dark (
  &:where([data-neural-mode='dark'], [data-neural-mode='dark'] *)
);

A popup is clipped, too narrow or behind another surface

A parent with overflow: hidden, a transformed containing block or a competing top layer can constrain an inline panel. Use the component's documented appendTo="body" support when the panel must escape that layout. Do not solve ordinary clipping with arbitrary global z-index escalation.

<neural-select
  [options]="countries"
  appendTo="body"
  ariaLabel="Country"
/>

<neural-date-picker
  [(value)]="deliveryDate"
  appendTo="body"
/>

• Keep trigger and panel in the same document.
• Verify an ancestor is not scaled during opening.
• Close overlays before destroying or replacing their trigger.
• Test start/end positions in both LTR and RTL.

The form value or state does not update

Hydration reports a mismatch

Compare the server and first browser render before inspecting later interaction. Locale, direction, selected values, generated collection order and conditional branches must initially agree. Defer localStorage, viewport measurement, current time and random values until a browser render callback.

Click, keyboard or focus behaves differently

• Check whether the control is disabled, readonly, loading or covered by another layer.
• Use the documented key contract for the component orientation and direction.
• Do not remove native focus outlines without an equivalent visible indicator.
• When a modal closes, keep its trigger mounted so focus can be restored.

npm reports an Angular peer conflict

Install a NeuralNg release whose manifest includes your Angular major. The current Core contract is Angular 22.x. Avoid --force and --legacy-peer-deps; they hide the compatibility error without making the runtime safe.