Resonance Design System
☰

Inputs Single and multiline text fields.

Table of contents

Usage guidelines

When to use
  • Inputs should be used when there is a need for freeform text. If there are heavy restrictions on allowed content, consider using a control (radio, select, checkbox, or switch) instead.
How to use
  • All inputs should have labels associated with them.
  • The <label> element should be the first child of the <res-input>.
  • You can optionally include placeholder text that includes non-critical guidance or an example of good input.
  • Placeholder text can be added using the native placeholder attribute on the <input type="text">.
  • Consider using helper text and tooltips to provide contextual information or guidance where needed. When relevant, consider linking to relevant documentation.
  • Helper text can be added by inserting an element with an attribute of slot="help" after the native input element.
  • All labels, placeholders, helper text, and tooltips should be in sentence case.
Accessibility
  • Placeholder text isn’t always visible and may be inaccessible on screenreaders. It should contain only additional, optional information that reinforces the label rather than replaces it.
Content guidelines
  • Input labels should be nouns (e.g., Dek, Caption, Tags, Keyname).
  • If the input’s purpose or behavior isn’t immediately clear from the label, include a tooltip to explain how it works.
  • Do not repeat the label as placeholder text. Only use placeholder text if it helps people understand how to format their text.
    • Example from embeds:
      • Input label: Embed URL
      • Placeholder text: https://youtu.be/KaOC9danxNo
      • Tooltip text: Paste the link to a Tweet, Instagram, YouTube or other embed.

Variations

Helper text

Use helper text to communicate additional information required for someone to properly use the input. For instance, required characters for password fields.

To use helper text, add an element with the attribute slot="help".

Character Count

Use a character count when there are a maximum number of characters that can be inserted.

To add a character count, add the count attribute (and a number) directly to the res-input element.

Inner slot

Use an inner slot when a descriptive icon needs to be added to the form field for better context.

To use inner slots, add the slot="inner-left" or slot="inner-right" attribute directly to a res-icon element inside of the input component.

Outer slot

Use an outer slot when a button needs to be appended to a form field.

To use outer slots, add the slot="outer-left" or slot="outer-right" attribute directly to a res-button element inside of the input component.

Inner and outer slots

Use both inner and outer slots together for more complex fields that need both actionable buttons and contextual icons.

Attributes

An asterisk next to a value denotes that it is the default value for that attribute. Unless noted otherwise, attributes should be added to the component element directly. Boolean attributes work based on their presence or absence from the component.

<res-component booleanAttribute stringAttribute="parameter">    
  <child-element></child-element>
</res-component>
AttributeTypeDescription
countintegerSet character limit and show counter
disabledbooleanSet initial state to disabled
errorstringSet error state along with message
infostringSet info state along with message
requiredbooleanSet required state
blockbooleanSet input to block display
use-as-res-inputbooleanUsed to set a non-input child element as the input (e.g. contentEditable divs)

API

NameTypeDataDescription
disabledpropertybooleanGet/set disabled state
requiredpropertybooleanGet/set required state
errorpropertystringGet/set error state (pass string to set message)
infopropertystringGet/set info state (pass string to set message)
countpropertyintegerGet/set character limit (pass false to remove limit)

Slots

SlotDescAccepts
helpHelp text for input
inner-leftPlaces an icon inside input on left sideres-icon
inner-rightPlaces an icon inside input on right sideres-icon
outer-leftPlaces a button next on left side of inputres-button
outer-rightPlaces a button next on right side of inputres-button

Notes

Depends on:
Required DOM

Without these, the component will throw an error on render.

  • <input|textarea> - Input element
Supported optional DOM

If added as children, these elements will receive specific styles and/or functionality.

  • <label> - Label element

History

VersionNote
0.25.3Adds ability to add a res-select to the outer right slot
0.21.4Adds variable fallbacks that satisfy updated linting rules, package upgrades cause CSS build to remove -moz-appearance property
0.19.0Adds info attribute, which renders information below the input
0.18.0Add min-width to icons inside inputs and error text so that they don't shrink, remove forced capitalization of input error text
0.15.6Remove the inputSelector attribute from res-input in favor of using use-as-res-input attribute on the non-input element.
0.15.5Add res-icon hover style (via hover attribute). Replace faux-input with inputSelector attribute for passing allowable selectors.
0.15.0Add block attribute and increase line height for labels, textarea, and help text. Add faux-input attribute to allow usage of Quill div with contenteditable.
0.14.0Add required attribute.
0.12.0Apply new spacing scale. Remove 'smallest' size attribute from warning icons in error messages.
0.11.0Tweaks to accommodate new icon set.
0.10.0Color update
0.7.0Web component refactor. First component to use psuedo-slots. Removed clear attribute.
0.5.0Total refactor! Accepts all input types now. API much thinner since the input is fully customizable. Added clear attribute.
0.4.0Allow error messages to be set via attribute. Update API to allow strings on set. Refactor how help messages, error messages, and character counts are styled.
0.3.0Darker input text color.
0.2.0Consistent padding to match other elements.
0.1.0Initial build to spec.