Estados (UF)

Unidades federativas: siglas, nomes, códigos do IBGE, capitais, regiões e fusos horários.

Listar

Retorna as 27 unidades da federação, ordenadas por nome (ordenação pt-BR).

Cada item tem a sigla de duas letras, o nome, o código e o nome da região e o código IBGE de 2 dígitos.
Cada chamada retorna um array novo com objetos novos.

Parâmetro	Tipo	Obrigatório
retorna	`State[]`

Retorna todos os estados brasileiros, cada um com sigla, nome, código da região, nome da região e código IBGE de 2 dígitos (cUF).

Ordenados por nome no locale "pt-BR".
Exporta os tipos State, StateCode e StateName. State é uma união discriminada: estreitá-lo pelo code também estreita os demais campos.

import { getStates } from '@brazilian-utils/brazilian-utils';

getStates();
// [
//   { code: 'AC', name: 'Acre', regionCode: 'N', regionName: 'Norte', ibgeCode: 12 },
//   { code: 'AL', name: 'Alagoas', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 27 },
//   { code: 'AP', name: 'Amapá', regionCode: 'N', regionName: 'Norte', ibgeCode: 16 },
//   { code: 'AM', name: 'Amazonas', regionCode: 'N', regionName: 'Norte', ibgeCode: 13 },
//   { code: 'BA', name: 'Bahia', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 29 },
//   { code: 'CE', name: 'Ceará', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 23 },
//   { code: 'DF', name: 'Distrito Federal', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 53 },
//   { code: 'ES', name: 'Espírito Santo', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 32 },
//   { code: 'GO', name: 'Goiás', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 52 },
//   { code: 'MA', name: 'Maranhão', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 21 },
//   { code: 'MT', name: 'Mato Grosso', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 51 },
//   { code: 'MS', name: 'Mato Grosso do Sul', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 50 },
//   { code: 'MG', name: 'Minas Gerais', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 31 },
//   { code: 'PA', name: 'Pará', regionCode: 'N', regionName: 'Norte', ibgeCode: 15 },
//   { code: 'PB', name: 'Paraíba', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 25 },
//   { code: 'PR', name: 'Paraná', regionCode: 'S', regionName: 'Sul', ibgeCode: 41 },
//   { code: 'PE', name: 'Pernambuco', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 26 },
//   { code: 'PI', name: 'Piauí', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 22 },
//   { code: 'RJ', name: 'Rio de Janeiro', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 33 },
//   { code: 'RN', name: 'Rio Grande do Norte', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 24 },
//   { code: 'RS', name: 'Rio Grande do Sul', regionCode: 'S', regionName: 'Sul', ibgeCode: 43 },
//   { code: 'RO', name: 'Rondônia', regionCode: 'N', regionName: 'Norte', ibgeCode: 11 },
//   { code: 'RR', name: 'Roraima', regionCode: 'N', regionName: 'Norte', ibgeCode: 14 },
//   { code: 'SC', name: 'Santa Catarina', regionCode: 'S', regionName: 'Sul', ibgeCode: 42 },
//   { code: 'SP', name: 'São Paulo', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 35 },
//   { code: 'SE', name: 'Sergipe', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 28 },
//   { code: 'TO', name: 'Tocantins', regionCode: 'N', regionName: 'Norte', ibgeCode: 17 },
// ]

Fonte: IBGE Localidades

Código: brazilian-utils/javascript

Teste com JavaScript getStates

Casos de teste compartilhados (1) e o resultado em cada biblioteca state.list

Os casos, em JSON

Get by ibge code

Retorna o estado cujo código IBGE de 2 dígitos (cUF, o código no primeiro campo da chave de acesso de um DF-e) corresponde a code.

code pode ser uma string ou um inteiro não negativo.
De uma string, todo caractere que não é dígito é removido antes, como na 2.4.0: "35/SP" e " 35 " resolvem para São Paulo.
Um número negativo ou fracionário não é lido como código e retorna null.
O resultado tem a sigla, o nome, o código da região, o nome da região e o código IBGE.
Retorna null quando o código não corresponde a nenhum estado.

Parâmetro	Tipo	Obrigatório
`code`	`string \| number`	sim
retorna	`State \| null`

Retorna o estado brasileiro cujo código IBGE de 2 dígitos (cUF, o Código da Unidade da Federação) corresponde ao valor informado.

É o código de UF do primeiro campo de uma chave de acesso de DF-e, a que isValidNfeKey cobre.
Aceita string ou número inteiro não negativo, com todo caractere que não é dígito removido da string ('35/SP' é 35).
Retorna null quando o código não corresponde a nenhum estado. Exporta o tipo State.

import { getStateByIbgeCode } from '@brazilian-utils/brazilian-utils';

getStateByIbgeCode('35');
// { code: 'SP', name: 'São Paulo', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 35 }

getStateByIbgeCode(11);
// { code: 'RO', name: 'Rondônia', regionCode: 'N', regionName: 'Norte', ibgeCode: 11 }

getStateByIbgeCode('00'); // null
getStateByIbgeCode(-35); // null
getStateByIbgeCode(3.5); // null

Fonte: IBGE Localidades, Manual de Orientação do Contribuinte

Código: brazilian-utils/javascript

Teste com JavaScript getStateByIbgeCode

Casos de teste compartilhados (12) e o resultado em cada biblioteca state.getByIbgeCode

Os casos, em JSON

Get capital

Retorna a capital de um estado, no mesmo formato de municipality.getByCode: o código IBGE de 7 dígitos, o nome e a sigla da UF.

A comparação ignora maiúsculas e minúsculas e espaços nas pontas: "to" e " TO " dão Palmas.
O Distrito Federal não tem municípios. A capital é Brasília, com o código que o IBGE dá ao distrito inteiro (5300108).
Retorna null para uma string que não é sigla de estado e para um valor que não é string.
O tipo State não tem campo de capital. A capital vem só desta função.
Cada chamada retorna um objeto novo.

Parâmetro	Tipo	Obrigatório
`stateCode`	`string`	sim
retorna	`Municipality \| null`

Retorna a capital de um estado brasileiro, no mesmo formato { code, name, stateCode } (Municipality) que o getMunicipalityByCode retorna para ela.

A busca ignora maiúsculas e minúsculas e os espaços nas pontas. Retorna null quando nenhum estado corresponde.
O Distrito Federal não é dividido em municípios, mas o IBGE o codifica como um só, Brasília, e essa é a sua capital.

import { getStateCapital } from '@brazilian-utils/brazilian-utils';

getStateCapital('SP'); // { code: '3550308', name: 'São Paulo', stateCode: 'SP' }
getStateCapital('to'); // { code: '1721000', name: 'Palmas', stateCode: 'TO' }
getStateCapital('DF'); // { code: '5300108', name: 'Brasília', stateCode: 'DF' }
getStateCapital('ZZ'); // null

Fonte: IBGE, Anuário Estatístico do Brasil, tabela 1.1.1.2 (capitais, 2025)

Código: brazilian-utils/javascript

Teste com JavaScript getStateCapital

Casos de teste compartilhados (15) e o resultado em cada biblioteca state.getCapital

Os casos, em JSON

Get code by name

Retorna a sigla de duas letras de um estado a partir do nome completo.

A comparação ignora acentos, maiúsculas e minúsculas e espaços nas pontas. Espaços internos seguidos viram um só espaço.
Só o nome completo corresponde. A sigla (SP) e um nome escrito sem os espaços (saopaulo) retornam null.
Retorna null quando nenhum estado corresponde.

Parâmetro	Tipo	Obrigatório
`name`	`string`	sim
retorna	`StateCode \| null`

Retorna a sigla de um estado brasileiro a partir do nome completo.

A comparação ignora acentos, não diferencia maiúsculas de minúsculas e remove os espaços nas pontas; espaços internos repetidos viram um só.
Retorna null quando nenhum estado corresponde. Exporta o tipo StateCode.

import { getStateCodeByName } from '@brazilian-utils/brazilian-utils';

getStateCodeByName('São Paulo'); // 'SP'
getStateCodeByName('sao paulo'); // 'SP'
getStateCodeByName('  Rio de Janeiro  '); // 'RJ'
getStateCodeByName('Neverland'); // null

Fonte: IBGE, API de Localidades, estados

Código: brazilian-utils/javascript

Teste com JavaScript getStateCodeByName

Casos de teste compartilhados (20) e o resultado em cada biblioteca state.getCodeByName

Os casos, em JSON

Get name by code

Retorna o nome completo de um estado a partir da sigla de duas letras.

A comparação ignora maiúsculas e minúsculas e espaços nas pontas.
Retorna null quando nenhum estado corresponde.

Parâmetro	Tipo	Obrigatório
`code`	`string`	sim
retorna	`StateName \| null`

Retorna o nome completo de um estado brasileiro a partir da sigla.

A comparação não diferencia maiúsculas de minúsculas e remove os espaços nas pontas.
Retorna null quando nenhum estado corresponde. Exporta o tipo StateName.

import { getStateNameByCode } from '@brazilian-utils/brazilian-utils';

getStateNameByCode('SP'); // 'São Paulo'
getStateNameByCode('sp'); // 'São Paulo'
getStateNameByCode('  Rj  '); // 'Rio de Janeiro'
getStateNameByCode('ZZ'); // null

Fonte: IBGE, API de Localidades, estados

Código: brazilian-utils/javascript

Teste com JavaScript getStateNameByCode

Casos de teste compartilhados (9) e o resultado em cada biblioteca state.getNameByCode

Os casos, em JSON

Get regions

Retorna as cinco Grandes Regiões do IBGE, ordenadas pelo identificador do IBGE: Norte (1), Nordeste (2), Sudeste (3), Sul (4) e Centro-Oeste (5).

Cada item tem o código da região (N, NE, SE, S, CO, o mesmo regionCode de cada estado), o nome e o identificador do IBGE.
O tipo State não tem campo com o identificador da região. O identificador vem só desta função.
Cada chamada retorna um array novo com objetos novos.

Parâmetro	Tipo	Obrigatório
retorna	`Region[]`

Retorna as cinco Grandes Regiões do Brasil, cada uma com o código (o mesmo regionCode de cada estado), o nome e o identificador do IBGE, na ordem desse identificador. Exporta os tipos Region e RegionCode.

import { getRegions } from '@brazilian-utils/brazilian-utils';

getRegions();
// [
//   { code: 'N', name: 'Norte', ibgeCode: 1 },
//   { code: 'NE', name: 'Nordeste', ibgeCode: 2 },
//   { code: 'SE', name: 'Sudeste', ibgeCode: 3 },
//   { code: 'S', name: 'Sul', ibgeCode: 4 },
//   { code: 'CO', name: 'Centro-Oeste', ibgeCode: 5 },
// ]

Fonte: IBGE, API de Localidades, regioes.

Código: brazilian-utils/javascript

Teste com JavaScript getRegions

Casos de teste compartilhados (1) e o resultado em cada biblioteca state.getRegions

Os casos, em JSON

Get timezone

Retorna o fuso horário IANA (zona tzdata) de um estado: a zona da capital, por exemplo America/Sao_Paulo.

Alguns estados atravessam mais de um fuso, e o fuso da capital não diz nada sobre o resto. O oeste do Amazonas (America/Eirunepe, UTC-5) e o oeste do Pará (America/Santarem, UTC-3) não são representados, e Fernando de Noronha (America/Noronha, UTC-2), um distrito de Pernambuco, resolve como Recife (America/Recife, UTC-3).
Os deslocamentos seguem as capitais: Acre UTC-5; Amazonas, Roraima, Rondônia, Mato Grosso e Mato Grosso do Sul UTC-4; os outros estados UTC-3. Um mesmo fuso do tzdata pode servir vários estados (America/Sao_Paulo também cobre DF, GO, MG, ES, RJ, PR, SC e RS, e America/Fortaleza também cobre MA, PI, RN e PB além do CE).
A comparação ignora maiúsculas e minúsculas e espaços nas pontas.
A hora legal do Brasil é a do Decreto 2.784/1913, alterado pela Lei 11.662/2008 (revogada) e pela Lei 12.876/2013, que restabeleceu os fusos do Acre e do sudoeste do Amazonas. Os nomes dos fusos vêm da base IANA. O horário de verão (Decreto 8.112/2013) não é fonte desta função.
Retorna null quando nenhum estado corresponde.

Parâmetro	Tipo	Obrigatório
`stateCode`	`string`	sim
retorna	`string \| null`

Retorna o nome do fuso horário IANA (zona do tzdata) de um estado brasileiro: o fuso da sua capital.

Alguns estados abrangem mais de um fuso, e o fuso da capital não diz nada sobre o resto: o oeste do Amazonas (America/Eirunepe, UTC-5) e o oeste do Pará (America/Santarem, UTC-3) não são representados, e Fernando de Noronha (America/Noronha, UTC-2), distrito de Pernambuco, resolve como Recife (UTC-3). Os deslocamentos seguem as capitais: Acre UTC-5; Amazonas, Roraima, Rondônia, Mato Grosso e Mato Grosso do Sul UTC-4; os demais estados UTC-3.
A comparação não diferencia maiúsculas de minúsculas e remove os espaços nas pontas.
Retorna null quando nenhum estado corresponde.

import { getTimezoneByState } from '@brazilian-utils/brazilian-utils';

getTimezoneByState('SP'); // 'America/Sao_Paulo'
getTimezoneByState('am'); // 'America/Manaus'
getTimezoneByState('AC'); // 'America/Rio_Branco'
getTimezoneByState('PE'); // 'America/Recife'
getTimezoneByState('ZZ'); // null

Fonte: IANA Time Zone Database, Decreto 2.784/1913, que fixou a hora legal do Brasil, alterado pela Lei 11.662/2008 e pela Lei 12.876/2013.

Código: brazilian-utils/javascript

Teste com JavaScript getTimezoneByState

Casos de teste compartilhados (35) e o resultado em cada biblioteca state.getTimezone

Os casos, em JSON

List by region

Retorna os estados de uma região, dado o código dela: N, NE, SE, S ou CO.

A comparação ignora maiúsculas e minúsculas e espaços nas pontas: "co" e " CO " dão a mesma lista.
Os estados vêm ordenados por nome, como em state.list, com os mesmos campos.
Retorna uma lista vazia para um código desconhecido (inclusive um nome de região como Norte) e para um valor que não é string.
Cada chamada retorna um array novo com objetos novos.

Parâmetro	Tipo	Obrigatório
`regionCode`	`string`	sim
retorna	`State[]`

Retorna os estados de uma região, dado o código dela ('N', 'NE', 'SE', 'S' ou 'CO'), em ordem alfabética, como o getStates ordena.

A busca ignora maiúsculas e minúsculas e os espaços nas pontas. Retorna [] quando nenhuma região corresponde.

import { getStatesByRegion } from '@brazilian-utils/brazilian-utils';

getStatesByRegion('S').map((state) => state.code); // ['PR', 'RS', 'SC']
getStatesByRegion('co').map((state) => state.code); // ['DF', 'GO', 'MT', 'MS']
getStatesByRegion('X'); // []