A standard input field with many options including various masked types, error or hint displays, and much more.
Format Modifiers give you a granular level of control over the behavior of the field, which are different for each input type.
alphaThe type credit-card input masking and iconography include Amex, Discover, Mastercard, Visa, and Dinersclub. Information about credit card number masks and shapes can be found in this Baymard credit card article.
In your use of q2-input you may experience the need to use a button instead of just a plain icon on the right or left side of the input field. For this reason, we've added two slots you may use to make this possible.
input-leftWith this slot, you can add a button to the left-hand side of the q2-input field.
<q2-input label="My Input Field">
<q2-btn slot="input-left">
<q2-icon type="calculator">
</q2-icon>
</q2-btn>
</q2-input>input-rightWith this slot, you can add a button to the right-hand side of the q2-input field.
<q2-input label="My Input Field">
<q2-btn slot="input-right">
<q2-icon type="add">
</q2-icon>
</q2-btn>
</q2-input>If you need to display a label with more complexity, you may use the label slot to do just that. It allows you to provide complex HTML markup while still resulting in semantic code. Here is an example of how you can use it:
<q2-input>
<div slot="label">
Full Name
<q2-tooltip label="First and last name" position="e">
<q2-icon inline type="question"></q2-icon>
</q2-tooltip>
</div>
</q2-input>Tecton aims to accurately replicate native browser APIs wherever possible. The checkValidity API can be somewhat tricky, so it's important to outline its expected behavior.
When you interact with the <q2-input> component, it updates the validity property in the same way a regular <input /> field does. However, if you need to check the validity at runtime, it's best to use the checkValidity method.
When you call checkValidity(), it returns a boolean value indicating whether the element is valid. If the input is in an invalid state, it will also emit an "invalid" event that you can listen for. From there, you can check the validity property of the component to access the corresponding validity object it provides.
<q2-input
label="State Abbreviation"
pattern="[A-Za-z]{2}"
></q2-input>
<q2-btn
intent="workflow-secondary"
>
Check Validity
</q2-btn>
<script>
const myInput = document.querySelector("q2-input");
const checkBtn = document.querySelector("q2-btn");
checkBtn.addEventListener("click", async () => {
await myInput.checkValidity();
});
myInput.addEventListener("invalid", async (result) => {
console.log("VALIDITY", myInput.validity);
});
</script>The q2-input element has multiple slots that can be used to insert custom content into the component.
An optional slot to display custom content in the input field.
An optional slot to add a Button on the left-hand side of the input field.
An optional slot to add a Button on the right-hand side of the input field.
An optional slot to display a custom label.
The q2-input element has one or more properties that support text localization. Those properties are indicated by the localizable badge in the description.
autocapitalizeThe autocapitalize attribute is an enumerated attribute that controls whether and how text input is automatically capitalized as it is entered/edited by the user.
This attribute only affects the behavior of input mechanisms like virtual keyboards on mobile devices and voice input.
autocompleteThe HTML autocomplete attribute lets web developers specify what permission (if any) the user agent has to provide automated assistance in filling out form field values, as well as guidance to the browser as to the type of information expected in the field.
autocorrectA string that indicates whether or not to activate automatic correction while the user is editing this field.
This is currently only supported in Safari.
autofocusAutofocus is enabled when the property is added to an element. To disable, remove attribute or set it to false. If applied to multiple elements, the first one will receive focus.
badgeThemebadge-themeThe color of the badge when in the active state. The property badgeValue must be provided.
badgeValuebadge-valueDisplays a q2-badge element on the right side of the input.
clearableRenders an icon button when the field is non-empty. Pressing the button clears all input from the field.
currentIf provided a value, it sets the aria-current attribute on the inner input.
See MDN for more information on aria-current.
disabledIndicates the field cannot be focused or interacted with.
errorsEach item in the errors array will appear below the input field when the field is focused.
formatModifierformat-modifierDefines the field's expected input format, and automatically masks user input to conform. Specific types support different modifier options. See the section on Format Modifiers for all available options.
hideLabelhide-labelHide's the field's <label> element from view.
Only use when a visible label is impractical.
hideMessageshide-messagesWhen true and the input field has an active validation error, the field shows the error state without displaying associated error messages below the field (from the errors array).
Primarily used for dropdown selects and date pickers whose controls appear below the input field (where the error messages, if displayed, would also appear).
hintsEach item in the hints array will appear below the input field when the field is focused.
The errors array takes precedence over the hints array. If an input field has both hints and errors, only the errors will display.
Once all errors are resolved, the hints display the next time the field is focused.
iconLefticon-leftShows a left-aligned q2-icon within the field.
iconRighticon-rightShows a right-aligned q2-icon within the field.
labelThe label that appears above the field. This is announced by screen readers when the field is focused.
maxWhen present, it does not allow a value greater than max when the user uses the Up/Down arrow keys to change the value.
Only applicable when type="number".
maxlengthDefines the maximum allowed input length in characters. Formatting characters (e.g. ., -, etc) are included in the maxlength comparison.
Make sure you account for them when setting the maxlength value. Input types that use masks have their own inherent maxlength.
minWhen present, it does not allow a value less than the min when the user uses the Up/Down arrow keys to change the value.
Only applicable when type="number".
optionalAppends "(optional)" to the field label, and sets aria-required on the nested input tag to false.
patternApplies the value as a RegEx pattern to assess the validity of the input field's value.
Check the ValidityState's patternMismatch property for the result.
Example:
<q2-input label="My input" pattern="[a-zA-Z0-9]{3,5}" id="myInput"></q2-input>
// enter "abcdefgh" in the input field (too many characters)
const myInput = document.querySelector('#myInput');
console.log(myInput.validity.patternMismatch); // trueplaceholderText that appears within the field when it is blurred and empty. Placeholder text disappears when the user focuses on the field and provides input.
Primarily used for rare cases in which a visible form label is not expected (e.g., search fields).
pseudoComponent will display as a clickable <button> styled to be identical to the default <input> field.
readonlyAppends "(read only)" to the field label, and field becomes unusable, but remains focusable.
Takes priority over optional if both are true.
showCountshow-countShows a character counter above the input field to track the number of characters currently in the field.
If maxlength is set, showCount displays the number of characters in relation the maxlength value.
showVisibilityToggleshow-visibility-toggleDisplays a toggle button at the end of the input field which shows or hides the actual value.
Only applicable when type is text, password, or ssn.
stepWhen present, it jumps the value in increments of step when the user uses the Up/Down arrow keys to change the value.
Only applicable when type="number".
textHiddentext-hiddenControls visibility of the value when the type is text, password, or ssn.
When the input type is password, it will default to true, hiding the text.
typeSpecifies the field's expected input type, and provides the optimal keyboard on mobile devices.
validityReturns a read-only ValidityState object representing the validity states of the element.
See MDN for more information on ValidityState.
valueThe value of the input field.
The visible value of formatted input fields may not match the element's value property.
When setting an input's value programmatically (e.g. pre-populating a form), ensure that the supplied value is in a format that can be handled by its consuming logic.
q2-input does not change its own value outside of its default change event handler.
In q2-input where type="currency"
The q2-input element exposes events that can be used to send and receive data from the component based on user interaction.
Emitted when the field loses focus after the value has been changed.
IEventDetailIf an event handler is bound to the element using:
onchange property - The default handler will not fire, and the value must be updated in the custom handler.addEventListener("change") method - The default handler will fire alongside the custom handler.Emitted when the field value is cleared.
Requires the clearable prop to be set to true.
undefinedEmitted when the field value is formatted.
IFormatterValueObjectEmitted when the field value is updated.
IEventDetailIf an event handler is bound to the element using:
oninput property - The default handler will not fire, and the value must be updated in the custom handler.addEventListener("input") method - The default handler will fire alongside the custom handler.Emitted when the validation is updated.
IEventDetailIf an event handler is bound to the element using:
oninvalid property - The default handler will not fire, and the value must be updated in the custom handler.addEventListener("invalid") method - The default handler will fire alongside the custom handler.The q2-input element exposes methods that can be used to perform various actions on the component.
Emulates firing checkValidity on <input>, emits invalid event if validation failed.
checkValidity() => Promise<boolean>Emulates clicking the clear button when the input is clearable.
clearValue() => Promise<void>Only applicable when the input is clearable.
Emulates focusing the <input>, entering the provided value, and emitting an input event.
This method leaves the focus on the <input> and as a result does not trigger the change event. If you want
to trigger the change event, move the focus to another element after calling this method.
setValue(value: string) => Promise<void>This component uses other components in the Tecton library, including:
q2-iconq2-btnq2-badgeOther components in the Tecton library use this component, including:
q2-calendarq2-editable-fieldq2-paginationq2-selectInitial Release
Add slots for input-left and input-right
Added the following {{format-modifier}} options for {{numeric}} types:
Ndecimal-delimited-positiveNdecimal-positiveNdecimal-delimitedinteger-delimited-positiveinteger-positiveinteger-delimitedThe type attribute of an input element directly affects both its behavior and user expectations. For example, setting the input type to "credit-card" (or a custom implementation using "text" with formatting logic) allows the input to visually match standard credit card number formatting and may include an associated icon to reinforce the context.
Use the correct input type to ensure optimal usability, accessibility, and user trust. For example:
Choosing the appropriate input type enhances both semantic meaning and interaction affordance.
We discourage relying on placeholder text as a primary method for conveying information. Placeholders disappear on focus, making them an unreliable mechanism for users to reference during data entry—particularly for users with visual or cognitive impairments.
However, when used appropriately, placeholder text can provide brief and contextually helpful hints—such as an example of the expected input format (e.g., MM/YY for expiration dates). Placeholder text should supplement, not replace, form labels or help text. It must not be the only source of essential guidance.
Sensitive inputs, such as passwords, credit card numbers, or social security numbers, should be masked by default to protect user privacy. When text is hidden, always provide a visibility toggle to allow users to reveal and verify their input when needed. This helps prevent errors and improves usability without compromising security.
When integrating input slots using q2-input components with q2-icon, follow consistent conventions to ensure clarity and usability:
Signifiers communicate specific actions or states. They should be clearly recognizable and aligned with established mental models or help establish new ones. Icons must accurately reflect their associated behavior to prevent confusion.
The following CSS variables are available to override the default theme styles of the q2-inputcomponent.
Many Tecton components consume other components to maintain visual and functional consistency. If you are looking for a CSS variable you think should exist but are not seeing it, it may be defined in one of the dependent components below. Either way, if you think it's something we should expose more conveniently, let us know!
There are 3 frequently asked questions related to this page.