PHPackages vsilva472/jquery-viacep - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. vsilva472/jquery-viacep ActiveLibrary[Utility & Helpers](/categories/utility) vsilva472/jquery-viacep ======================= Plugin jquery para autocompletar endereços a partir de um cep utilizando a api do viaCEP 1.0.3(6y ago)9571[1 issues](https://github.com/vsilva472/jquery-viacep/issues)MITJavaScript Since Jul 9Pushed 5y ago2 watchersCompare [ Source](https://github.com/vsilva472/jquery-viacep)[ Packagist](https://packagist.org/packages/vsilva472/jquery-viacep)[ Docs](https://github.com/vsilva472/jquery-viacep)[ RSS](/packages/vsilva472-jquery-viacep/feed)WikiDiscussions master Synced 3w ago READMEChangelog (4)DependenciesVersions (4)Used By (0) jQuery ViaCEP ============= [](#jquery-viacep) [![license](https://camo.githubusercontent.com/a78678804a0492258832d3043a4ac4821fa8ecab9088a510e620a6ce31b87e84/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7673696c76613437322f6a71756572792d7669616365702e7376673f7374796c653d666c61742d737175617265)](https://github.com/vsilva472/jquery-viacep/blob/master/LICENSE) [![Release](https://camo.githubusercontent.com/7c95fe75fa082f105e685aa9e0af341921ee70ee8b2d388ca0ae81913b87cf7c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f7673696c76613437322f6a71756572792d7669616365702e7376673f7374796c653d666c61742d737175617265)](https://github.com/vsilva472/jquery-viacep/releases) [![](https://camo.githubusercontent.com/d471251b2cd84b99a83a7c0656605f75a8127624518ede7c71649658b6597a44/68747470733a2f2f646174612e6a7364656c6976722e636f6d2f76312f7061636b6167652f6e706d2f407673696c76613437322f6a71756572792d7669616365702f6261646765)](https://www.jsdelivr.com/package/npm/@vsilva472/jquery-viacep) [![npm](https://camo.githubusercontent.com/436a6c8815612498ad4fe078f49457815ff91b21838284a3a53404d0fdb00a1b/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f646d2f407673696c76613437322f6a71756572792d7669616365702e7376673f7374796c653d666c61742d737175617265)](https://www.npmjs.com/package/@vsilva472/jquery-viacep) Um plugin jQuery para autocompletar endereços a partir de um CEP utilizando a api do site [ViaCEP](https://viacep.com.br) com ~1,6Kb. Elaborado de forma não intrusiva, ou seja, não é necessário alterar o código existente da aplicação. Compatível com gerenciadores de Tags (como Google Tagmanager) e com suporte a múltiplos forms na mesma página. Compatível ainda com vários CMSs e Frameworks (Laravel, WooCommerce e etc). Conteúdo -------- [](#conteúdo) - [Suporte de browser](#suporte-de-browser) - [Instalação](#instala%C3%A7%C3%A3o) - [Via Git](#instala%C3%A7%C3%A3o-via-git) - [NPM](#instala%C3%A7%C3%A3o-via-npm) - [Composer](#instala%C3%A7%C3%A3o-via-composer) - [CDN](#instala%C3%A7%C3%A3o-via-CDN) - [Opções padrão](#op%C3%A7%C3%B5es-padr%C3%A3o) - [Instruções de uso](#instru%C3%A7%C3%B5es-de-uso) - [Via data-attributes](#usando-com-seletores-padr%C3%A3o-via-data-attributes) - [Via classes css](#usando-com-seletores-padr%C3%A3o-via-classes-css) - [Seletores mistos](#usando-com-seletores-mistos) - [Uso com jQuery Mask](#uso-em-conjunto-com-jquery-mask) - [Eventos](#eventos) - [Exemplos avançados](#exemplos-avan%C3%A7ados) - [Exibindo loading](#exibindo-loading) - [Bloqueando FORM durante o loading](#bloqueando-form-durante-o-loading) - [Bloquear campos autocompletados](#bloquear-campos-autocompletados) - [Dropdown de estados sem UF](#dropdown-de-estados-sem-uf) - [Integrando com Laravel](#integrando-com-laravel) - [Integrando com Google Analytics](#integrando-com-google-analytics) - [Integrando com Google TagManager](#integrando-com-google-tagmanager) - [Integrando com Select2](#integrando-com-select2) - [Campos gia, ibge, unidade e complemento](#campos-gia-ibge-unidade-e-complemento) - [Apoie o projeto](#apoie) Suporte de Browser ------------------ [](#suporte-de-browser) [![Internet Explorer](https://user-images.githubusercontent.com/4265802/60848376-bf7bdc80-a1bc-11e9-89db-5637ebad0352.png)](https://user-images.githubusercontent.com/4265802/60848376-bf7bdc80-a1bc-11e9-89db-5637ebad0352.png)[![Chrome](https://user-images.githubusercontent.com/4265802/60848375-bee34600-a1bc-11e9-82bd-ab65ee37dd52.png)](https://user-images.githubusercontent.com/4265802/60848375-bee34600-a1bc-11e9-82bd-ab65ee37dd52.png)[![Firefox](https://user-images.githubusercontent.com/4265802/60848374-bee34600-a1bc-11e9-84d3-7338811bf48d.png)](https://user-images.githubusercontent.com/4265802/60848374-bee34600-a1bc-11e9-84d3-7338811bf48d.png)[![Opera](https://user-images.githubusercontent.com/4265802/60848373-bee34600-a1bc-11e9-9eb0-f72e9a75a14b.png)](https://user-images.githubusercontent.com/4265802/60848373-bee34600-a1bc-11e9-9eb0-f72e9a75a14b.png)[![Safari](https://user-images.githubusercontent.com/4265802/60848372-be4aaf80-a1bc-11e9-8c4e-680f7c0f21e4.png)](https://user-images.githubusercontent.com/4265802/60848372-be4aaf80-a1bc-11e9-8c4e-680f7c0f21e4.png)IE 10+ ✔Último ✔Último ✔Último ✔Último ✔Instalação ---------- [](#instalação) ##### Instalação via GIT [](#instalação-via-git) `git clone git@github.com:vsilva472/jquery-viacep.git` (SSH) ou `git clone https://github.com/vsilva472/jquery-viacep.git` (HTTPS) ##### Instalação via NPM [](#instalação-via-npm) `npm i @vsilva472/jquery-viacep --save` ##### Instalação via Composer [](#instalação-via-composer) `composer require vsilva472/jquery-viacep` ##### Instalação via CDN [](#instalação-via-cdn) `` Opções padrão ------------- [](#opções-padrão) ``` $.fn.viacep.defaults = { container : '[data-viacep]', field_logradouro: '[data-viacep-endereco], .viacep-endereco', field_bairro: '[data-viacep-bairro], .viacep-bairro', field_localidade: '[data-viacep-cidade], .viacep-cidade', field_uf: '[data-viacep-estado], .viacep-estado', field_cep: '[data-viacep-cep], .viacep-cep' }; ``` AtributoTipoPadrãoDescriçãocontainerString`'[data-viacep]'`Seletor do container dos campos (geralmente a tag ``)field\_logradouroString`'[data-viacep-endereco], .viacep-endereco'`Seletor para o campo Endereço do formfield\_bairroString`'[data-viacep-bairro], .viacep-bairro'`Seletor para o campo bairro do formfield\_localidadeString`'[data-viacep-cidade], .viacep-cidade'`Seletor para o campo Cidade do formfield\_ufString`'[data-viacep-estado], .viacep-estado'`Seletor para o campo Estado do formfield\_cepString`'[data-viacep-cep], .viacep-cep'`Seletor para o campo CEP do formSe seu projeto possui vários formulários e todos são padronizados, talvez seja mais prático para você alterar as opções padrão globalmente, dessa forma basta incluir o arquivo com as opções preenchidas e o plugin se encarregará do resto. ``` // arquivo vicep.configs.js $.fn.viacep.defaults = { container: '.form', field_logradouro: '.logradouro', field_bairro: '.bairro', field_localidade: '.cidade', field_uf: '.estado', field_cep: '.cep' }; $('.form').viacep(); ``` Instruções de uso ----------------- [](#instruções-de-uso) ### Usando com seletores padrão via *data-attributes* [](#usando-com-seletores-padrão-via-data-attributes) ``` ``` **Nota** Se você utilizar os seletores padrão definidos em `$.fn.viacep.defaults` inalterados, não é necessário a chamada do plugin `$('selector').viacep(options)`, pois o plugin já se auto instancia com essas opções. ### Usando com seletores padrão via classes *CSS* [](#usando-com-seletores-padrão-via-classes-css) ``` $('.form').viacep(); ``` ### Usando com seletores *mistos* [](#usando-com-seletores-mistos) O plugin é flexível o suficiente para misturar seletores padrão com personalizados. O exemplo abaixo usa os seletores padrão de classe css para o campo `bairro` e o seletor padrão de `data-attribute` para o campo `cidade` e seletores personalizados para os demais campos. ``` $('[name="cadastro-pessoa"]').viacep({ field_logradouro: '[data-endereco-personalizado]', field_uf: '#uf', field_cep: '.cep' }); ``` **Nota** A chamada para o plugin **deve ser feita em uma tag que englobe os campos** a serem auto completados (geralmente na tag ``). ### Uso em conjunto com jQuery Mask [](#uso-em-conjunto-com-jquery-mask) Este plugin não faz bind de valores no campo de cep, isto torna jquery-viacep um plugin compatível com outros plugins de máscaras como por exemplo o [jQuery Mask](https://igorescobar.github.io/jQuery-Mask-Plugin/) de forma nativa. Entretanto caso você precise/deseje fazer alguma programação customizada na(s) máscara(s) do(s) campo(s) antes e/ou depois de receber os dados da api, você pode estar consultando a [api de eventos](#eventos) e identificar qual melhor evento se adapta a sua necessidade de customização da máscara. ``` (...) $('.cep').mask('00000-000'); ``` Eventos ------- [](#eventos) O plugin possui uma poderosa api de eventos que o torna extensível e flexível o suficiente para ser integrável em qualquer sistema que possua `jQuery` instalado. EventoDescriçãoArgumentos`viacep.plugin.init`Disparado logo após o plugin ser iniciado em um elemento`NULL``viacep.ajax.before`Disparado antes de efetuar a requisição para api do viaCEP`NULL``viacep.ajax.complete`Disparado no final do ciclo da requisição independente se a mesma foi obteve sucesso ou erro.`NULL``viacep.ajax.error`Disparado quando ocorre um erro na requisição (400, 500 etc.)`jqxhr, textStatus, error``viacep.ajax.success`Disparado quando a requisição é feita com sucesso e após os bind dos valores nos campos`response` completo incluindo os campos `unidade`, `ibge` e `gia` da api do ViaCEP`viacep.response.error`Disparado quando a requisição foi feita com sucesso porém o objeto json da resposta da api contém o atributo `erro``cep, msg, response`Exemplos avançados ------------------ [](#exemplos-avançados) Veja abaixo algumas aplicações avançadas do plugin utilizando a api de eventos do plugin. ### Exibindo loading [](#exibindo-loading) ``` .hide { display: none; } Aguarde... $("[data-viacep]").on('viacep.ajax.before viacep.ajax.complete', function () { $(this).find('.loading').toggleClass('hide'); }); ``` ### Bloqueando FORM durante o loading [](#bloqueando-form-durante-o-loading) As vezes faz-se necessário bloquear o `form` durante a requisição para evitar múltiplas requisições. O exemplo abaixo ilustra essa situação. ``` Endereço $('#form-1').on('viacep.ajax.before', function () { //$(this).find('.loading').removeClass('hide'); $(this).find('fieldset').attr('disabled', true); }) .on( 'viacep.ajax.complete', function () { //$(this).find('.loading').addClass('hide'); $(this).find('fieldset').removeAttr('disabled'); }); ``` ### Bloquear campos autocompletados [](#bloquear-campos-autocompletados) Algumas vezes devido a uma regra de negócio, não desejamos permitir que o usuário altere os campos depois que foram preenchidos. O exemplo abaixo ilustra esta situação deixando apenas o campo número liberado para preenchimento. ``` $('#form-2').on( 'viacep.ajax.complete', function () { var $this = $( this ), fields_to_block = ['cep', 'endereco', 'bairro', 'cidade', 'estado']; fields_to_block.forEach(function (name) { $this.find('[name="' + name + '"]').attr('disabled', true); }); }); ``` ### Dropdown de estados sem UF [](#dropdown-de-estados-sem-uf) Por padrão o plugin tentará setar o valor do campo estado com o atributo `uf` da resposta da api. Isto funcionará normalmente caso o campo `estado` seja um campo de texto ou seja um `` com ``. Alguns projetos utilizam o nome do estado ao invés da `uf` nos ``. O exemplo abaixo ilustra como proceder nesse caso. ``` Rio de Janeiro São Paulo $('#form-3').on( 'viacep.ajax.success', function (e, response) { $(this).find('#estado').val(response.localidade).trigger('change'); }); ``` ### Integrando com Laravel [](#integrando-com-laravel) Em frameworks como laravel é comum por questões de segurança a existência de um `CSRF-TOKEN` para evitar ataques, e por uma questão de comodidade geralmente já inserimos o header `X-CSRF-TOKEN` nas requisições ajax com um script do tipo: ``` $.ajaxSetup({ headers: { 'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content') } }); ``` Porém a api do viaCEP não completa a requisição se este header estiver presente. O exemplo abaixo ilustra como proceder neste caso desativando este header e reativando ao final da requisição. ``` (...) $('#form-4').on('viacep.ajax.before', function () { // remover o header para esta requisicao delete $.ajaxSettings.headers["X-CSRF-TOKEN"]; }).on('viacep.ajax.complete', function () { // readicionar o header para outras requisições internas ao projeto. $.ajaxSettings.headers["X-CSRF-TOKEN"] = $('meta[name="csrf-token"]').attr('content'); }); ``` ### Integrando com Google Analytics [](#integrando-com-google-analytics) Talvez seja interessante para e equibe de BI extrair algumas informações sobre essas buscas no google analytics. O exemplo abaixo ilustra como enviar um evento com o nome da cidade buscada para o GA. Você pode adpatar para sua necessidade. ``` (...) $('#form-5').on( 'viacep.ajax.success', function ( e, response ) { ga( 'send', 'event', 'CEP', 'buscar', response.localidade ); }); ``` ### Integrando com Google TagManager [](#integrando-com-google-tagmanager) O exemplo abaixo ilustra a situação anterior porém enviando o evento via TagManager ao invés do GA . ``` (...) $('#form-6').on( 'viacep.ajax.success', function ( e, response ) { dataLayer.push({ event: 'sendToGA', eventCategory: 'CEP', eventAction: 'buscar', eventLabel: response.localidade }); }); ``` ### Integrando com Select2 [](#integrando-com-select2) Este plugin está programado para funcionar com a biblioteca `Select2` de forma nativa. Caso você precise de algum ajuste, você pode estar utilizando a api do `select2` em conjunto com a api de eventos deste plugin, em específico o evento `viacep.ajax.success` para refazer o bind dos valores no `select2`. Veja: ``` (...) $('#form-7').on( 'viacep.ajax.success', function ( e, response ) { // utilizar a api do select2 // @see https://select2.org/programmatic-control }); ``` ### Campos gia ibge unidade e complemento [](#campos-gia-ibge-unidade-e-complemento) Talvez em seu(s) formulário(s) você precise do(s) campo(s) `gia` e/ou `ibge` e/ou `complemento` e/ou `unidade`. Você pode estar populando estes campos de 3 formas: 1. Definindo-os nas configurações globais em `$.fn.viacep.defaults` ``` (...) $.fn.viacep.defaults = { container : '[data-viacep]', field_logradouro: '[data-viacep-endereco], .viacep-endereco', field_bairro: '[data-viacep-bairro], .viacep-bairro', field_localidade: '[data-viacep-cidade], .viacep-cidade', field_uf: '[data-viacep-estado], .viacep-estado', field_cep: '[data-viacep-cep], .viacep-cep', // campos customizados field_gia: '.gia', field_ibge: '.ibge', field_complemento: '.complemento', field_unidade: '.unidade', }; $('[data-viacep]').viacep(); ``` 2. Definindo os campos na instancia do plugin ``` (...) $('#form-8').viacep({ field_gia: '.gia', field_ibge: '.ibge', field_complemento: '.complemento', field_unidade: '.unidade', }); ``` 3. Populando os campos via evento `viacep.ajax.success` (recomendado). Esta opção é a recomendada pois nela você tem maior controle sobre os dados recebidos e os campos que você precisa popular. Atente-se que nem sempre o resposta da api do viaCEP retorna com estes dados populados. ``` (...) $('#form-9').on('viacep.ajax.success', function (e, response) { // TO DO implementar validações $(this).find('.gia').val(response.gia); $(this).find('.unidade').val(response.unidade); $(this).find('.ibge').val(response.ibge); $(this).find('.complemento').val(response.complemento); // Ex: concatenar o complemento no campo endereço $(this).find('#endereco').val(response.logradouro + ' ' + response.complemento); }); ``` ### Apoie [](#apoie) Apoie o projeto enviando **HTMLCOIN** Wallet: **HqgaiK6T1o2JP4p3p34CZp2g3XnSsSdCXp** [![Doar HTMLCoin](https://camo.githubusercontent.com/e61dbbdfd04786128d92a39d5c4b4956ea23c4af8e61b0e2516eed029627a10c/68747470733a2f2f7777772e76696e69636975736465736f757a612e636f6d2e62722f696d672f68746d6c636f696e2e706e67)](https://camo.githubusercontent.com/e61dbbdfd04786128d92a39d5c4b4956ea23c4af8e61b0e2516eed029627a10c/68747470733a2f2f7777772e76696e69636975736465736f757a612e636f6d2e62722f696d672f68746d6c636f696e2e706e67) #### Licença [](#licença) MIT ### Health Score 29 — LowBetter than 57% of packages Maintenance18 Infrequent updates — may be unmaintained Popularity15 Limited adoption so far Community9 Small or concentrated contributor base Maturity61 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~155 days Total 3 Last Release 2233d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/4265802?v=4)[Vinicius Silva](/maintainers/vsilva472)[@vsilva472](https://github.com/vsilva472) --- Top Contributors [![vsilva472](https://avatars.githubusercontent.com/u/4265802?v=4)](https://github.com/vsilva472 "vsilva472 (27 commits)") --- Tags cepcorreioscorreios-cepjavascriptjqueryviacepjquerycorreioscepviacepcep-autocomplete ### Embed Badge ![Health badge](/badges/vsilva472-jquery-viacep/health.svg) ``` [![Health](https://phpackages.com/badges/vsilva472-jquery-viacep/health.svg)](https://phpackages.com/packages/vsilva472-jquery-viacep) ``` ### Alternatives [yajra/laravel-datatables-oracle jQuery DataTables API for Laravel 4.9k35.3M364](/packages/yajra-laravel-datatables-oracle)[flyingluscas/correios-php Uma maneira fácil de interagir com as principais funcionalidades dos Correios. 140365.7k3](/packages/flyingluscas-correios-php)[flyingluscas/viacep-php ViaCEP PHP SDK 3540.5k](/packages/flyingluscas-viacep-php)[jansenfelipe/cep-gratis Com esse pacote você poderá realizar consultas de CEP gratuitamente. 689.6k](/packages/jansenfelipe-cep-gratis)[jarouche/viacep Classe para pesquisar o CEP atraves do servico gratuito viacep 3425.0k](/packages/jarouche-viacep)[claudsonm/cep-promise-php Busca por CEP utilizando Promises nos serviços dos Correios, ViaCEP, CepAberto e outros. 3020.9k](/packages/claudsonm-cep-promise-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)