Voter ID

Check if a voter ID number is valid. A voter ID has at most 12 digits, so a 13-digit value is rejected.

• A voter ID is an 8-digit sequential number, a 2-digit federative union code (01 to 28) and 2 check digits.
• The TSE drops the leading zeros of the sequential number when it issues the ID, so a shorter value is read as the ID without them and left padded with zeros to 12 digits before it is checked (123450159 is checked as 000123450159). At least one sequential digit is required: the shortest accepted value has 5 digits.
• Whitespace, dots, hyphens and slashes are accepted around and between the groups. Any other character makes the value invalid.
• Resolução TSE nº 23.659/2021, art. 36, which revoked Resolução TSE nº 21.538/2003 (art. 140), fixes the layout, the federative union table and two check digits "determinados com base no 'Módulo 11'". It gives no weights and no rule per state: the weights, and the rule that turns a remainder of 0 into 1 for São Paulo (01) and Minas Gerais (02), have no official source and follow the community references below.

import { generateVoterId, isValidVoterId } from '@brazilian-utils/brazilian-utils';

const voterId = generateVoterId('SP');

isValidVoterId(voterId); // true
isValidVoterId('102385010671'); // true (12 digits)
isValidVoterId('123450159'); // true (000123450159 issued without its leading zeros)
isValidVoterId('1234567880191'); // false (13 digits, more than the 12 the TSE allows)
isValidVoterId('123456780124'); // false (invalid check digits)

Source: Resolução TSE nº 23.659/2021, art. 36 ("composto por até 12 algarismos", "os oito primeiros algarismos serão sequenciados, desprezando-se, na emissão, os zeros à esquerda"), brutils and siga0984.

Format a voter ID number with the 12-digit grouping 0000 0000 00 00.

• Options (FormatVoterIdOptions): pad left pads the value with zeros up to 12 digits, restoring the leading zeros of a voter ID issued without them; obfuscate hides the first 3 digits and the 2 check digits, leaving the federative union code visible. The mask hides by position, so pass pad with obfuscate for a voter ID given as a number, which has lost its leading zeros: without it the mask shifts onto the check digits. An empty value, or one without digits, gives '' even with pad.
• Without pad, a shorter value is formatted from the left, as a partially typed ID.
• Digits past the 12th are dropped.
• No authority publishes a masking rule for the voter ID, so obfuscate applies the one the Leis de Diretrizes Orçamentárias set for publishing a CPF ("ocultar os três primeiros dígitos e os dois dígitos verificadores", Lei nº 14.194/2021, art. 149, first set by Lei nº 12.309/2010, art. 87, § 5º), a number with the same structure.

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

formatVoterId('123456780175'); // '1234 5678 01 75'
formatVoterId('123456780175', { obfuscate: true }); // '***4 5678 01 **'
formatVoterId('123450159', { pad: true }); // '0001 2345 01 59'
formatVoterId('123450159'); // '1234 5015 9' (read as a partially typed ID)

Remove voter ID formatting, keep only digits, and cap the result to 12 digits. A shorter value is kept as it is, without adding leading zeros.

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

parseVoterId('1234 5678 01 75'); // '123456780175'
parseVoterId('12345 01 59'); // '123450159'

Generate a valid random voter ID number. The optional state argument (StateCode, or "ZZ" for a voter ID issued abroad) sets the federative union code.

• state ignores letter case and surrounding whitespace ('sp' is 'SP'). An unknown state, or a value that is not a string, falls back to "ZZ" (UF 28).
• The result always has 12 digits, the leading zeros of the sequential number included; the same ID without them is valid too.

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

generateVoterId(); // valid random voter ID (abroad, "ZZ")
generateVoterId('SP'); // valid random voter ID for Sao Paulo
generateVoterId('XX'); // falls back to "ZZ" instead of throwing

Source: Lei nº 14.194/2021, art. 149, the CPF masking rule obfuscate borrows, first set by Lei nº 12.309/2010, art. 87, § 5º and repeated by the later LDOs (Lei nº 15.321/2025, art. 163, the one for 2026, repeats it).

Read the fields of a voter ID, as a VoterIdInfo, or null when isValidVoterId would return false.

• Fields: sequentialNumber (8 digits), federativeUnion (the code '01' to '28'), stateCode (a StateCode, or null for '28', the voters abroad) and checkDigits (2 digits). Codes are strings that keep their leading zeros.
• A voter ID issued without the leading zeros of its sequential number is read as isValidVoterId reads it, left padded with zeros to 12 digits: '123450159' gives the sequentialNumber '00012345'.
• The stateCode is the federative union of the registration, not necessarily where the voter lives today.

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

getVoterIdInfo('1023 8501 06 71');
// {
//   sequentialNumber: '10238501',
//   federativeUnion: '06',
//   stateCode: 'PR',
//   checkDigits: '71',
// }

getVoterIdInfo('000000002801'); // { sequentialNumber: '00000000', federativeUnion: '28', stateCode: null, checkDigits: '01' }
getVoterIdInfo('123456780124'); // null (invalid check digits)

Source: Resolução TSE nº 23.659/2021, art. 36.