Appearance

Field ​

The Field component is the main building block for most of Stash's form components, including Input, Select, and Textarea. It includes several props (ex: label, hint-text), styles, and functionlity to ensure all of our form components are consistent.

WARNING

Designers are not the intended audience for the Field component. Field is used by engineers to build higher-order form components like Input and Select.

To see example usage, check out the source code for existing Stash components that use Field, such as Input, RadioGroup, and FilterSelect.

Fieldset ​

The default top-level HTML element rendered by <Field> is a <div>; using the fieldset prop will change this element to fieldset, which is useful for fields that contain multiple controls.

Sign me up?
template
<Field fieldset label="Sign me up?">
  <Radio id="yes" v-model="fieldset" name="fieldset" label="Yes" value="yes" />
  <Radio id="no" v-model="fieldset" name="fieldset" label="No" value="no" />
</Field>

Static and read-only ​

When displaying static/read-only data within a <form>, it is recommended to use <Input is-read-only :model-value="myField" /> (or <Select is-read-only>, etc.) instead of using <Field is-read-only> or <DescriptionList variant="stacked"> or <Input is-disabled /> (see Disabled vs read-only).

The styling for <Input is-read-only> matches <DescriptionList variant="stacked">. DescriptionList is a better fit when the field is not displayed within a <form>.

Disabled vs read-only ​

The difference between disabled and readonly is that read-only controls can still function and are still focusable, whereas disabled controls can not receive focus and are not submitted with the form and generally do not function as controls until they are enabled. Source

Benefits of read-only over disabled:

  1. Read-only inputs offer accessibility benefits over disabled inputs because they are focusable and therefore readable by a screenreader.
  2. Additionally, if the form method is PUT, it would be better to use readonly because disabled inputs get excluded from the form data.
  3. The <form> element in JavaScript has access to read-only fields within it, but not disabled fields

So when should we use disabled inputs?

A disabled input is preferable when the field should be editable eventually, such as when the field depends on the value of another editable form field.

API ​

See the documentation below for a complete reference to all the props and classes available to the components mentioned here.