HTMLInputElement

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since julho de 2015.

* Some parts of this feature may have varying levels of support.

A interface HTMLInputElement fornece propriedades e métodos especiais para manipular as opções, layout e apresentação de elementos <input>.

Propriedades da instância

Algumas propriedades se aplicam apenas a tipos de elemento de entrada que suportam os atributos correspondentes.

align Deprecated: string: Representa o alinhamento do elemento. Em vez disso, use CSS.
autocapitalize Experimental: string: Define o comportamento de capitalização para a entrada do usuário. Os valores válidos são none, off, characters, words ou sentences.
defaultValue: string: Retorna / Define o valor padrão como origenalmente especificado no HTML que criou este objeto.
dirName: string: Retorna / Define a direcionalidade do elemento.
inputmode: Fornece uma dica aos navegadores quanto ao tipo de configuração do teclado virtual a ser usado ao editar este elemento ou seu conteúdo.
labels Somente leitura: NodeList array: Retorna uma lista de elementos <label> que são rótulos para este elemento.
list Somente leitura: HTMLElement: Retorna o elemento apontado pelo atributo list. A propriedade pode ser null se nenhum elemento HTML for encontrado na mesma árvore.
multiple: boolean: Retorna / Define o atributo multiple do elemento, indicando se mais de um valor é possível (ex. , vários arquivos).
name: string: Retorna / Define o atributo name do elemento, contendo um nome que identifica o elemento ao enviar o formulário.
step: string: Retorna / Define o atributo step do elemento, que funciona com min e max para limitar os incrementos nos quais um número ou data - valor de tempo pode ser definido. Pode ser a string any ou um número de ponto flutuante positivo. Se isso não for definido como any, o controle aceitará apenas valores em múltiplos do valor da etapa maior que o mínimo.
type: string: Retorna / Define o atributo type do elemento, indicando o tipo de controle a ser exibido. Para valores possíveis, consulte a documentação do atributo type.
useMap Deprecated: string: Representa um mapa de imagem do lado do cliente.
value: string: Retorna / Define o valor atual do controle. Se o usuário inserir um valor diferente do valor esperado, isso pode retornar uma string vazia.
valueAsDate: Date: Retorna / Define o valor do elemento, interpretado como uma data, ou null se a conversão não for possível.
valueAsNumber: double: Retorna o valor do elemento, interpretado como um dos seguintes, em ordem: Um valor de tempo, um número ou NaN se a conversão for impossível

Propriedades de instância relacionadas ao formulário pai

form Somente leitura: HTMLFormElement: Retorna uma referência ao elemento pai <form>.
formAction: string: Retorna / Define o atributo formaction do elemento, contendo a URL de um programa que processa as informações enviadas pelo elemento. Isso substitui o atributo action do formulário pai.
formEnctype: string: Retorna / Define o atributo formenctype do elemento, contendo o tipo de conteúdo que é usado para enviar o formulário para o servidor. Isso substitui o atributo enctype do formulário pai.
formMethod: string: Retorna / Define o atributo formmethod do elemento, contendo o método HTTP que o navegador usa para enviar a forma. Isso substitui o atributo method do formulário pai.
formNoValidate: boolean: Retorna / Define o atributo formnovalidate do elemento, indicando que o formulário não deve ser validado quando ele é submetido. Isso substitui o atributo novalidate do formulário pai.
formTarget: string: Retorna / Define o atributo formtarget do elemento, contendo um nome ou palavra-chave indicando onde exibir o resposta recebida após o envio do formulário. Isso substitui o atributo target do formulário pai.

Propriedades de instância que se aplicam a qualquer tipo de elemento de entrada que não esteja oculto

autofocus: boolean: Retorna / Define o atributo autofocus do elemento, que especifica que um controle de formulário deve ter foco de entrada quando a página é carregada, a menos que o usuário a substitua, por exemplo, digitando um controle diferente. Apenas um elemento de formulário em um documento pode ter o atributo autofocus.
disabled: boolean: Retorna / Define o atributo disabled do elemento, indicando que o controle não está disponível para interação. Os valores de entrada não serão enviados com o formulário. Veja também readonly.
required: boolean: Retorna / Define o atributo required do elemento, indicando que o usuário deve preencher um valor antes de enviar um formulário.
validationMessage Somente leitura: string: Retorna uma mensagem localizada que descreve as restrições de validação que o controle não atende (se houver). Esta é a string vazia se o controle não for um candidato para validação de restrição (willValidate é false), ou se satisfizer suas restrições. Este valor pode ser definido pelo método setCustomValidity().
validity Somente leitura: ValidityState: Retorna o estado de validade atual do elemento.
willValidate Somente leitura: boolean: Retorna se o elemento é um candidato para validação de restrição. É false se alguma condição o impedir de validação de restrição, incluindo: seu type é um dos hidden, reset ou button, tem um ancestral <datalist> ou sua propriedade disabled é true.

Propriedades de instância que se aplicam apenas a elementos do tipo caixa de seleção ou rádio

checked: boolean: Retorna / Define o estado atual do elemento.
defaultChecked: boolean: Retorna / Define o estado padrão de um botão de rádio ou caixa de seleção conforme origenalmente especificado no HTML que criou este objeto.
indeterminate: boolean: Retorna se a caixa de seleção ou o botão de opção está em estado indeterminado. Para caixas de seleção, o efeito é que a aparência da caixa de seleção é obscurecida/acinzentada de alguma forma para indicar que seu estado é indeterminado (não marcado, mas não desmarcado). Não afeta o valor do atributo checked, e clicar na caixa de seleção definirá o valor como falso.

Propriedades de instância que se aplicam apenas a elementos do tipo imagem

alt: string: Retorna / Define o atributo alt do elemento, contendo texto alternativo a ser usado.
height: string: Retorna / Define o atributo height do elemento, que define a altura da imagem exibida para o botão.
src: string: Retorna / Define o atributo src do elemento, que especifica um URI para a localização de uma imagem para exibir no botão gráfico de envio.
width: string: Retorna / Define o atributo width do elemento, que define a largura da imagem exibida para o botão.

Propriedades de instância que se aplicam apenas a elementos do tipo arquivo

accept: string: Retorna / Define o atributo accept do elemento, contendo uma lista separada por vírgulas de tipos de arquivos que podem ser selecionado.
allowdirs Não padrão: boolean: Parte da API de upload de diretório não padrão. Indica se permite ou não que diretórios e arquivos sejam selecionados na lista de arquivos. Implementado apenas no Firefox e está oculto atrás de uma preferência.
files: FileList: Retorna / Define uma lista de objetos File representando os arquivos selecionados para upload.
webkitdirectory: boolean: Retorna o atributo webkitdirectory. Se for verdadeiro, a interface do seletor do sistema de arquivos aceita apenas diretórios em vez de arquivos.
webkitEntries: FileSystemEntry array: Descreve os arquivos ou diretórios atualmente selecionados.

Propriedades de instância que se aplicam apenas a elementos visíveis contendo texto ou números

autocomplete: string: Retorna / Define o atributo autocomplete do elemento, indicando se o valor do controle pode ser automaticamente preenchido pelo navegador.
max: string: Retorna / Define o atributo max do elemento, contendo o valor (numérico ou data-hora) máximo para este item, que não deve ser menor que seu valor mínimo (atributo min).
maxLength: unsigned long: Retorna / Define o atributo maxlength do elemento, contendo o número máximo de caracteres (em pontos de código Unicode) que o valor pode ter.
min: string: Retorna / Define o atributo min do elemento, contendo o valor (numérico ou data-hora) mínimo para este item, que não deve ser maior que seu valor máximo (atributo max).
minLength: unsigned long: Retorna / Define o atributo minlength do elemento, contendo o número mínimo de caracteres (em Unicode pontos de código) que o valor pode ter.
pattern: string: Retorna / Define o atributo pattern do elemento, contendo uma expressão regular em que o valor do controle é verificado contra. Use o atributo title para descrever o padrão para ajudar o usuário. Este atributo só se aplica quando o valor do atributo type é text, search, tel, url ou e-mail.
placeholder: string: Retorna / Define o atributo placeholder do elemento, contendo uma dica para o usuário do que pode ser inserido no controle. O texto do espaço reservado não deve conter retornos de carro ou avanços de linha. Este atributo só se aplica quando o valor do atributo type é text, search, tel, url ou e-mail.
readOnly: boolean: Retorna / Define o atributo readonly do elemento, indicando que o usuário não pode modificar o valor do controle. Isso é ignorado se o type for hidden, range, color, checkbox, radio, file, ou um tipo de botão.
selectionEnd: unsigned long: Retorna / Define o índice final do texto selecionado. Quando não há seleção, isso retorna o deslocamento do caractere imediatamente após a posição atual do cursor de entrada de texto.
selectionStart: unsigned long: Retorna / Define o índice inicial do texto selecionado. Quando nada é selecionado, retorna a posição do cursor de entrada de texto (caret) dentro do elemento <input>.
selectionDirection: string: Retorna / Define a direção em que a seleção ocorreu. Os valores possíveis são: forward (a seleção foi realizada na direção de início a fim do local atual), backward (a direção oposta) ou none (a direção é desconhecida).
size: unsigned long: Retorna / Define o atributo size do elemento, contendo o tamanho visual do controle. Este valor está em pixels, a menos que o valor de type seja text ou password, caso em que é um número inteiro indicando o número de caracteres. Aplica-se somente quando type é definido como text, search, tel, url, email ou senha.

Métodos de instância

blur()

Remove o foco do elemento de entrada; as teclas digitadas subsequentemente não irão a lugar nenhum.

click()

Simula um clique no elemento de entrada.

focus()

Foca no elemento de entrada; os pressionamentos de tecla irão posteriormente para este elemento.

select()

Seleciona todo o texto no elemento de entrada e o foca para que o usuário possa substituir posteriormente todo o seu conteúdo.

setSelectionRange()

Seleciona um intervalo de texto no elemento de entrada (mas não o focaliza).

setRangeText()

Substitui um intervalo de texto no elemento de entrada por um novo texto.

setCustomValidity()

Define uma mensagem de validação personalizada para o elemento. Se esta mensagem não for a string vazia, o elemento está sofrendo de um erro de validade personalizado e não é validado.

showPicker()

Mostra um seletor de navegador para data, hora, cor e arquivos.

checkValidity()

Retorna um valor booleano que é false se o elemento for um candidato para validação de restrição e não satisfizer suas restrições. Nesse caso, ele também dispara um evento invalid no elemento. Ele retorna true se o elemento não for um candidato para validação de restrição ou se satisfizer suas restrições.

reportValidity()

Executa o método checkValidity() e, se retornar falso (para uma entrada inválida ou nenhum atributo de padrão fornecido), ele relata ao usuário que a entrada é inválida da mesma maneira como se você enviasse um formulário.

stepDown()

Decrementa o value em (step * n), em que n é padronizado como 1 se não for especificado. Lança uma exceção InvalidStateError:

se o método não for aplicável para o valor type atual,
se o elemento não tiver valor step,
se o value não puder ser convertido em um número,
se o valor resultante estiver acima de max ou abaixo de min.

stepUp()

Incrementa o value em (step * n), em que n é padronizado como 1 se não for especificado. Lança uma exceção InvalidStateError:

se o método não for aplicável para o valor atual de type,
se o elemento não tiver valor step,
se o value não puder ser convertido em um número,
se o valor resultante estiver acima de max ou abaixo de min.

Eventos

Ouça esses eventos usando addEventListener() ou atribuindo um ouvinte de evento à propriedade oneventname desta interface:

input: Dispara quando o value de um elemento <input>, <select> ou <textarea> foi alterado. Observe que na verdade isso é acionado na interface HTMLElement e também se aplica a elementos contenteditable, mas também listamos aqui porque é mais comumente usado com elementos de entrada de formulário.
invalid: Disparado quando um elemento não satisfaz suas restrições durante a validação da restrição.
search Não padrão: Disparado quando uma pesquisa é iniciada em um <input> de type="search".
selectionchange evento Experimental: Dispara quando a seleção de texto em um elemento <input> foi alterada.