@kolkov/ngx-dadata

Angular autocomplete component for the Dadata.ru suggestions API.

Features

• Angular 19+ standalone component with signal-based inputs and outputs
• 24 Dadata suggestion types: address, FIO, party, bank, email, country, FIAS, and 17 more
• WAI-ARIA combobox pattern, WCAG AA accessible
• Keyboard navigation: ArrowUp/Down, Enter, Escape, Home, End
• ControlValueAccessor: works with both ngModel and reactive forms
• CSS custom properties for theming -- no style overrides needed
• Service API: getSuggestions, findById, geolocate, iplocate
• Web Components support via Angular Elements
• Tree-shakeable, OnPush change detection, SSR-safe (no direct DOM access)
• 182 tests, 93%+ code coverage

Requirements

Dependency	Version
Angular	>= 19.0.0
TypeScript	>= 5.5
RxJS	>= 7.0
Node.js	>= 18

Installation

npm install @kolkov/ngx-dadata

Quick Start (Standalone)

This is the recommended approach for Angular 19+.

1. Configure providers in your application config:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideNgxDadata, DadataType } from '@kolkov/ngx-dadata';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideNgxDadata({ apiKey: 'YOUR_DADATA_API_KEY', type: DadataType.address }),
  ],
};

2. Import the component and use it in your template:

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NgxDadataComponent, DadataSuggestion, DadataAddress } from '@kolkov/ngx-dadata';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FormsModule, NgxDadataComponent],
  template: `
    <ngx-dadata
      placeholder="Enter address"
      [(ngModel)]="address"
      (selected)="onSelected($event)"
    />
  `,
})
export class AppComponent {
  address = '';

  onSelected(suggestion: DadataSuggestion): void {
    const data = suggestion.data as DadataAddress;
    console.log('Selected:', suggestion.value, data);
  }
}

Quick Start (NgModule)

For projects that still use NgModule, the deprecated NgxDadataModule is available:

import { NgModule } from '@angular/core';
import { HttpClientModule } from '@angular/common/http';
import { NgxDadataModule } from '@kolkov/ngx-dadata';

@NgModule({
  imports: [HttpClientModule, NgxDadataModule],
})
export class AppModule {}

Then use <ngx-dadata> in your templates as shown above.

Note: NgxDadataModule is deprecated and will be removed in a future major version. Migrate to the standalone import with provideNgxDadata().

Configuration

Per-Component Config

Pass config directly via the [config] input:

<ngx-dadata
  [config]="{ apiKey: 'KEY', type: DadataType.party, limit: 5 }"
  (selected)="onSelected($event)"
/>

Global Config via DI

Use provideNgxDadata() at the application level. Per-component [config] takes priority over the DI config.

DadataConfig Reference

Property	Type	Default	Description
apiKey	string	''	Required. Your Dadata API key.
type	DadataType	'address'	Suggestion type (see DadataType enum below).
delay	number	500	Debounce delay in milliseconds before sending a request.
limit	number	10	Maximum number of suggestions returned.
partyAddress	'city' | 'full'	'city'	Address detail level shown for party suggestions.
locations	DadataLocation[]	--	Restrict suggestions to specific locations.
locationsBoost	DadataLocation[]	--	Boost suggestions from specific locations.
bounds	DadataBounds	--	Restrict granularity (fromBound / toBound).
restrictValue	boolean	--	(Address) Restrict displayed value to locations.
language	'ru' | 'en'	--	(Address) Response language.
locationsGeo	DadataLocationGeo[]	--	(Address) Geo-based location constraints.
division	'administrative' | 'municipal'	--	(Address) Administrative or municipal division.
entityType	'LEGAL' | 'INDIVIDUAL'	--	(Party) Filter by entity type.
status	string[]	--	(Party) Filter by organization status.
okved	string[]	--	(Party) Filter by OKVED codes.
branchType	'MAIN' | 'BRANCH'	--	(Party) Filter by branch type.
bankStatus	string[]	--	(Bank) Filter by bank status.
bankType	string[]	--	(Bank) Filter by bank type.
gender	'MALE' | 'FEMALE' | 'UNKNOWN'	--	(FIO) Filter by gender.
parts	('SURNAME' | 'NAME' | 'PATRONYMIC')[]	--	(FIO) Which name parts to suggest.

DadataType Enum

enum DadataType {
  // Primary
  address, fio, party, bank, email,
  // Extended
  fias, country, postal_unit,
  // International
  party_by, party_kz,
  // Classifiers
  currency, okved2, okpd2, oktmo, mktu,
  metro, fms_unit, fns_unit, fts_unit,
  court, car_brand,
  okpdtr_profession, okpdtr_position,
  medical_position,
}

Component Inputs and Outputs

Binding	Type	Description
[config]	DadataConfig	Configuration (optional if provideNgxDadata() is used).
[placeholder]	string	Input placeholder text. Default: ''.
[disabled]	boolean	Disables the input. Default: false.
(selected)	OutputEmitterRef<DadataSuggestion>	Emitted when a suggestion is selected.
ngModel / formControlName	string	Form binding for the input value.

Service API

Inject NgxDadataService for direct API access. When provideNgxDadata() is configured, the service picks up the global config automatically -- or you can pass a config per call.

getSuggestions

import { NgxDadataService, DadataType } from '@kolkov/ngx-dadata';

@Component({ /* ... */ })
export class MyComponent {
  private readonly dadata = inject(NgxDadataService);

  search(query: string): void {
    this.dadata.getSuggestions(query, {
      apiKey: 'KEY',
      type: DadataType.address,
      limit: 5,
      locations: [{ city: 'Moscow' }],
    }).subscribe(suggestions => {
      console.log(suggestions);
    });
  }
}

findById

Look up an entity by its identifier (FIAS ID, INN, OGRN, BIC, etc.):

this.dadata.findById('7707083893', DadataType.party).subscribe(results => {
  console.log(results);
});

geolocate

Find nearest addresses by coordinates:

this.dadata.geolocate(55.878, 37.653, {
  apiKey: 'KEY',
  radius_meters: 100,
  count: 5,
}).subscribe(suggestions => {
  console.log(suggestions);
});

iplocate

Determine address by IP:

this.dadata.iplocate('92.38.45.22', {
  apiKey: 'KEY',
  language: 'en',
}).subscribe(location => {
  console.log(location); // DadataSuggestion | null
});

Web Components

Use <ngx-dadata> in any HTML page, React, Vue, or other framework via Custom Elements.

1. Install the library and import the registration function:

import { registerNgxDadataElement } from '@kolkov/ngx-dadata/elements';

await registerNgxDadataElement({
  config: { apiKey: 'YOUR_API_KEY', type: 'address' },
});

2. Use in plain HTML:

<ngx-dadata placeholder="Enter address"></ngx-dadata>

<script type="module">
  import { registerNgxDadataElement } from './path/to/elements.js';
  await registerNgxDadataElement({ config: { apiKey: 'KEY' } });

  document.querySelector('ngx-dadata')
    .addEventListener('selected', (e) => {
      console.log('Selected:', e.detail);
    });
</script>

Calling registerNgxDadataElement() multiple times is safe -- subsequent calls are no-ops.

Theming

The component uses CSS custom properties with light-dark() defaults for automatic dark mode support. No extra configuration needed -- the component adapts to prefers-color-scheme out of the box.

Override tokens on the host element or any ancestor:

ngx-dadata {
  --ngx-dadata-bg: #f5f5f5;
  --ngx-dadata-border-radius: 12px;
  --ngx-dadata-focus-color: #0066cc;
}

Design Tokens

Global

Property	Default	Description
--ngx-dadata-font-family	inherit	Font family for all text.
--ngx-dadata-font-size	1rem	Base font size.
--ngx-dadata-transition-duration	150ms	Duration for all transitions (set to 0ms to disable).

Input

Property	Default	Description
--ngx-dadata-bg	light-dark(#fff, #1f2937)	Input background color.
--ngx-dadata-color	light-dark(#111827, #f9fafb)	Input text color.
--ngx-dadata-border-color	light-dark(#d1d5db, #374151)	Input border color.
--ngx-dadata-border-radius	8px	Input border radius.
--ngx-dadata-placeholder-color	light-dark(#9ca3af, #6b7280)	Placeholder text color.
--ngx-dadata-input-padding-x	12px	Horizontal padding inside the input.
--ngx-dadata-input-padding-y	10px	Vertical padding inside the input.
--ngx-dadata-focus-color	light-dark(#4a90d9, #60a5fa)	Focus outline color.
--ngx-dadata-disabled-opacity	0.5	Opacity when the input is disabled.

Dropdown

Property	Default	Description
--ngx-dadata-dropdown-bg	light-dark(#fff, #1f2937)	Dropdown panel background.
--ngx-dadata-dropdown-border-color	light-dark(#e5e7eb, #374151)	Dropdown border color.
--ngx-dadata-dropdown-shadow	light-dark(0 4px 6px -1px rgba(0,0,0,0.1), ...)	Dropdown box shadow.
--ngx-dadata-dropdown-max-height	300px	Maximum height before scrolling.
--ngx-dadata-dropdown-border-radius	0 0 8px 8px	Dropdown border radius (bottom corners).

Options

Property	Default	Description
--ngx-dadata-option-padding-x	12px	Horizontal padding for each option.
--ngx-dadata-option-padding-y	8px	Vertical padding for each option.
--ngx-dadata-hover-bg	light-dark(#f3f4f6, #374151)	Hovered option background.
--ngx-dadata-active-bg	light-dark(#4a90d9, #60a5fa)	Active (keyboard-selected) option background.
--ngx-dadata-active-color	light-dark(#fff, #111827)	Active option text color.
--ngx-dadata-detail-color	light-dark(#6b7280, #9ca3af)	Secondary detail text color (e.g., INN in party mode).
--ngx-dadata-detail-font-size	0.85em	Detail text font size.

Scrollbar

Property	Default	Description
--ngx-dadata-scrollbar-thumb	light-dark(#c1c1c1, #4b5563)	Scrollbar thumb color.
--ngx-dadata-scrollbar-track	transparent	Scrollbar track color.

Match Highlight

Property	Default	Description
--ngx-dadata-match-bg	light-dark(rgba(74,144,217,0.15), rgba(96,165,250,0.25))	Background for highlighted query matches.

Dark Mode

The component respects prefers-color-scheme automatically via color-scheme: light dark and light-dark() CSS function. To force a specific mode, set color-scheme on an ancestor:

/* Force dark mode */
.dark-theme ngx-dadata { color-scheme: dark; }

/* Force light mode */
.light-theme ngx-dadata { color-scheme: light; }

Accessibility Media Queries

The component handles these automatically:

• prefers-reduced-motion: reduce -- disables all transitions
• forced-colors: active -- uses system highlight colors (Windows High Contrast)
• pointer: coarse -- enlarges touch targets to 48px minimum

Accessibility

The component implements the WAI-ARIA Combobox pattern:

• role="combobox" on the container with aria-expanded, aria-owns, aria-haspopup
• role="searchbox" on the input with aria-autocomplete="list" and aria-activedescendant
• role="listbox" on the suggestion panel
• role="option" on each suggestion with aria-selected

Keyboard shortcuts:

Key	Action
ArrowDown	Move to next suggestion (wraps to first)
ArrowUp	Move to previous suggestion (wraps to last)
Enter	Select the active suggestion
Escape	Close the suggestion panel
Home	Jump to the first suggestion
End	Jump to the last suggestion

API Reference

Exports from @kolkov/ngx-dadata

Export	Kind	Description
NgxDadataComponent	Component	Standalone autocomplete component.
NgxDadataModule	NgModule	Deprecated wrapper for NgModule-based apps.
NgxDadataService	Service	Injectable service for direct API calls.
DadataType	Enum	Suggestion type identifiers.
DadataConfigDefault	Const	Default configuration object.
provideNgxDadata	Function	Provider factory for global DI config.
NGX_DADATA_CONFIG	InjectionToken	Token for providing DadataConfig via DI.
DadataConfig	Interface	Configuration interface.
DadataLocation	Interface	Location constraint.
DadataLocationGeo	Interface	Geo-based location constraint.
DadataBound	Interface	Single bound value.
DadataBounds	Interface	From/to bound pair.
GeolocateOptions	Interface	Options for geolocate().
IplocateOptions	Interface	Options for iplocate().
DadataSuggestion	Interface	A single suggestion from the API.
DadataResponse	Interface	API response wrapper.
DadataIplocateResponse	Interface	IP locate API response.
DadataAddress	Interface	Address data model.
DadataFIO	Interface	FIO (person name) data model.
DadataParty	Interface	Party (organization) data model.
DadataBank	Interface	Bank data model.
DadataEmail	Interface	Email data model.
DadataCountry	Interface	Country data model.
DadataFinance	Interface	Financial data (within party).
DadataPartyRef	Interface	Party reference (predecessors/successors).
DadataMetro	Interface	Metro station data (within address).

Exports from @kolkov/ngx-dadata/elements

Export	Kind	Description
registerNgxDadataElement	Function	Registers <ngx-dadata> as a Custom Element.
NgxDadataElementOptions	Interface	Options for element registration.

Contributing

Please read our Contributing Guide before submitting issues or pull requests.

License

MIT -- see LICENSE for details.

Copyright (c) 2018-present Andrey Kolkov