Input Field

Example

<vega-input
    id="input-id"
    name="input-name"
    label="Phone number"
    value="(555) 555-5555"
    autocomplete="off"
    prefix-icon="mobile-phone"
    required="true"
    max-length="14"
    auto-validation="true"
    validation-rules="object"
    hint="Enter your telephone number"
    show-clear-icon="true"
    >
</vega-input>

const vegaInput = document.getElementById("input-id");
vegaInput.maskConfig = { type: 'phone' };

Note: The above example uses Vanilla JS. If you would like to use React, Angular, or Vue, please consult Storybook.

To see an example of input fields in action, view the Form container.

Usage

The vega-input component is a standard form input field. Input fields are text fields which allow users to enter information directly onto a website. They can serve many purposes, ranging from search boxes to text fields and more.

Technically an input field refers to any field on a website form where a user can enter data, and it can include drop-downs, checkboxes, and more, however for our purposes, the input field refers specifically to a simple text input field.

Properties

Masks

You may use a mask to enforce an input format. Masks are supported for the following formats:

• phone
• taxid
• zipcode
• thousand-comma
• number
• custom

Custom masks can be created by passing the value “custom” to mask-config.type along with the slot and accept attributes.

• slot - Used to specify a formatting placeholder. You may use either a string or a regular expression.
• accept - This specifies acceptable characters. You may also use a regular expression here.

For example, say you wish to set up a mask to enforce Social Security Number (SSN) formatting. Specify the values as:

mask: "999-99-9999"
slot: "9"
accept: /d/

Or more specifically, as mask-config="{ type: 'custom', options: { mask: '999-99-9999', slot: '9', accept: /\d/ } }"

Mask Examples

<vega-flex
  direction="col"
  gap="size-12"
  use-native-flex="true"
>
  <vega-input
    id="mask-phone"
    label="phone"
    mask-config="{ type: 'phone' }"
    placeholder="(999) 999-9999"
  />
  <vega-input
    id="mask-taxId"
    label="taxId"
    mask-config="{ type: 'taxId' }"
    placeholder="99-9999999"
  />
  <vega-input
    id="mask-zipcode"
    label="zipcode"
    mask-config="{ type: 'mask-zipcode' }"
    placeholder="99999"
  />
  <vega-input
    id="mask-custom"
    label="custom"
    mask-config="{ type: 'custom', options: { mask: '999-99-9999', slot: '9', accept: /d/ } }"
    placeholder="999-99-9999"
  />
</vega-flex>

Validation

There are several validation rules which are specified through boolean attributes. The defined properties are as follows:

• required: the input value may not have an empty string: ''.
• email: the input value must be a valid email address.
• min: The minimum input value.
• max: The maximum input value.
• minLength: The minimum length of the input.
• maxLength: The maximum length of the input.

Validations for vega-input are automatically triggered by keyup or blur events.

You may also call the valid() method in order to manually trigger validation.

To get the validation result of vega-input you may use either of the following two methods:

1. Check the return value using the valid() method. Note: due to a StencilJS requirement, this method will return a Promise object. To get the fullfilled value of the Promise Object, use the await operator. A boolean ‘true’ indicates that the value is valid, whereas ‘false’ indicates that it is not valid.

Example:

document.getElementById('submit-btn').addEventListener('click', async () => {
    const vegaInput = document.getElementById('input-id');
    if (await vegaInput.valid()) {
        // valid
    } else {
        // invalid
    }
});

2. The second method involves using the isValid attribute of the vega-input.

Example:

<vega-input id="input-id" {...props}>
    {' '}
</vega-input>;

const vegaInput = document.getElementById('input-id');
if (vegaInput.isValid) {
    // valid
} else {
    // invalid
}

Value

The value attribute for vega-input behaves the same as in a standard HTML input field.

Example:

<vega-input id="input-id" value="demo" ... ></vega-input>


<script>
    const input_value = document.getElementById("input-id").value
</script>

Events

The vega-input component contains the following events”

• vegaChange - dispatched when the value of an input field is changed
• vegaValidate - dispatched when the validation result of a vega-input field is changed.
• vegaBlur - dispatched when a vega-input loses focus.

Examples

vegaChange

document.getElementById("input_id").addEventListener("vegaChange", (e) => { console.log(e.currentTarget.value)
})

vegaValidate

document.getElementById("input_id").addEventListener("vegaValidate", (e) => {
console.log(e.currentTarget.isValid) })

vegaBlur

document.getElementById("input_id").addEventListener("vegaBlur", (e) => { console.log(e.currentTarget.value)
})

For more details including examples for React and Vue, view in Storybook.

Accessibility

• Every form element must have a label.
• Ensure the autocomplete attribute is correct and suitable for the form field.
• Ensure that text spacing set through style attributes can be adjusted with custom stylesheets.
• Ensures buttons have discernible text.
• Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds.
• Ensures every id attribute value used in ARIA and in labels is unique.
• Ensures every id attribute value is unique.
• Ensures the form field does not have multiple label elements.
• Ensures that every form element is not solely labeled using the title or aria-describedby attributes.
• Nested interactive controls are not announced by screen readers.

Best Practices

One column layout: It’s generally easier for users to process information that is in one column. An exception can be made for fields which are commonly displayed on the same line, such as city, state and zip in an address.

Reduce number of fields: Within forms it’s generally best to keep the number of fields that a user must fill in to a minimum, or we run the risk of having a negative impact to the user experience. Thai is especially true for mobile applications where there is limited screen space. If you need to gather more information it’s wise to use only 5-7 fields at a time, and break the form into multiple pages.

Require fields: It’s generally considered good practice to require all fields. If not all fields are required, those fields which are required should be designated in some manner, such as a red asterisk. If using this method, always define the meaning of the asterisk below the form.

Default values: Avoid setting default values for forms; users will often skip fields that already have values.

Use Input masks: if your input requires a specific format, such as a phone number, date, or credit card number, it should automatically format the field to the correct format as the user types.

Keyboard friendly: all fields should be accessible by using only the keyboard, and users should not have to lift their hands to use a mouse or pointing device. This also increases the accessibility of the form.

Autofocus: it’s best to have the cursor already in a useful place so a person can start typing without clicking on the page.

Placeholders: Using placeholder text is problematic for several reasons. Text which disappears when clicking on it can be a strain on users’ short-term memory, and can create a number of accessibility issues. Research shows that users often tend not to notice fields with text in them, and may consider them to be already filled fields.

Contrast issues with lightly colored placeholder text can make it difficult for them to pass WCAG AA compliance. If they are made darker, they can easily be mistaken for already filled fields, causing the user to skip the field and possibly run into validation errors Placeholder text is also not necessarily read aloud by all screen readers, making the content unavailable to some disabled users.

For this reason, consider the following:

• Never use placeholders in place of the input field label.
• Consider using the built-in vega-input hint property to show the suggestions below the field instead of a placeholder.

Use good labels: All form fields should have labels, which enable focus by clicking on the label itself. The label should be above the input field, and not next to it to enable faster scanning. Do not use the placeholder text as the sole location for the label.

Do

Don't