Skip to content

Angular

@unicep/angular gives you signal and RxJS bindings, for Angular 17 or newer and RxJS 7. The package uses no decorators, so it works with the standard Angular build.

Janela do terminal
npm install @unicep/angular

@unicep/core is installed with it.

injectCep must be called in an injection context, such as in a field or constructor of a component or service.

import { Component, signal } from '@angular/core';
import { injectCep } from '@unicep/angular';
@Component({
selector: 'app-cep-field',
template: `
<input [value]="value()" (input)="value.set($any($event.target).value)" placeholder="00000-000" />
@if (cep.isLoading()) { <p>Searching…</p> }
@if (cep.error(); as error) { <p>{{ error.message }}</p> }
@if (cep.data(); as address) {
<p>{{ address.street }}, {{ address.neighborhood }} - {{ address.city }}/{{ address.state }}</p>
}
`,
})
export class CepFieldComponent {
readonly value = signal('');
readonly cep = injectCep(() => this.value());
}

The lookup only happens when the value is a valid CEP (with or without the hyphen). If the CEP changes, the previous result is dropped and the in-flight request is cancelled.

injectCep(cep: () => string | null | undefined, options?: {
unicep?: Unicep; // default: the instance provided through the UNICEP token
enabled?: () => boolean; // return false to pause lookups, default always enabled
}): {
data: Signal<Address | undefined>;
error: Signal<Error | undefined>;
isLoading: Signal<boolean>; // true while a lookup for the current valid CEP is in flight
}

The Observable version, for RxJS pipelines. Unsubscribing cancels the request.

import { inject } from '@angular/core';
import { lookupCep, UNICEP } from '@unicep/angular';
const unicep = inject(UNICEP);
lookupCep(unicep, '01310100').subscribe((address) => console.log(address));

UNICEP is the injection token for the Unicep instance. By default it is a shared instance with all built-in providers. To change providers, timeout, cache or circuit breaker, provide your own:

import { ApplicationConfig } from '@angular/core';
import { Unicep, viaCep, brasilApi } from '@unicep/core';
import { provideUnicep } from '@unicep/angular';
export const appConfig: ApplicationConfig = {
providers: [
provideUnicep(new Unicep({ providers: [viaCep(), brasilApi()], timeoutMs: 3000, cache: {} })),
],
};

error is one of the unicep errors, such as CepNotFoundError or AllProvidersFailedError. Every option is covered in Providers and Core.