Textfield

Textfield is an input field that enables users to type in data. It accepts data in various formats like text, numeric and password.Textfield is configurable to accept short or long form entries. You can configure its width and also attach SVG icons, words and React nodes to the input field.

The architecture of the Textfield family is flexible, so you can compose complex input fields as required.

Usage

import {
  Textfield,
  Email,
  Search
} from "@asphalt-react/textfield"

  <>
    <Textfield/>
    <Email/>
    <Search/>
  </>

Components

Textfield suite offers following components specific to the nature of the input -

• Textfield
• Email
• Password
• URL
• Numeric
• Search
• Datefield
• Timefield
• Pinfield

Qualifiers

Qualifiers provide a hint about the expected content of the field. They can be SVG icons or words. You can attach the qualifier using qualifierStart & qualifierEnd. Qualifiers works great for use-cases like attaching currency ISO codes or symbols to the Textfield.

Addons

Along with qualifiers, Textfields also accept React nodes (a.k.a addon) to attach them beside qualifiers. You can use addons to compose components like for a phone number field with country code selector as an addon. You can add the React nodes on either ends of the field input simultaneously.

By default addons are rendered on the extreme ends of the field. Adjacent to the addons qualifiers are rendered and they are attached to the ends of the input field. The order of these entities from start to end is addOnStart, qualifierStart, input field in the middle, qualifierEnd & addOnEnd. You can swap the positions of Qualifiers and AddOns such that qualifiers appear on the extreme ends while addOns take the middle slots.

Multiline

Apply multiline prop to accept multiple rows of text. Only Textfield supports multiline. Qualifiers don't work in multiline fields.

Building blocks

You can compose complex input fields with the help of the following building blocks that are part of the Textfield family.

Unit Components

The Textfield family comes with:

• InputWrapper
• InputQualifier
• InputAddOn
• Input

Hooks

Use the useInput() hook to get all the prop getter functions and then spread them in the right children components. Pass all the props in the useInput() hook as parameter.

import { 
  useInput, 
  InputWrapper,
  InputQualifier,
  InputAddOn,
  Input
} from "@asphalt-react/textfield"

const { getInputProps, getWrapperProps, getQualifierProps } = useInput(props)

<InputWrapper {...getWrapperProps()}>
  <InputQualifier {...getQualifierProps()}>
    <IconPlaceHolder />
  </InputQualifier>

  <Input {...getInputProps()} />

  <InputAddOn>
    <Button icon>
      <Add />
    </Button>
  </InputAddOn>
</InputWrapper>

Form validation & Attributes

1. All textfields support HTML form validations.
2. All textfields supports data-/* attributes & DOM attributes

Accessing through React ref

To get access to the underlying DOM element, pass a React ref in the ref prop.

Accessibility

1. All Textfields are focusable.
2. By default Numeric render input element with inputmode="numeric".
3. Textfields have aria-invalid attribute for components with invalid prop set to true.
4. All Textfields accept the aria-* attributes input role.

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

multiline

Enables the field to accept multiple lines of text.

Qualifiers do not work with multiline.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

extent

Controls the height of a multiline field. Accepts "low", "mid" & "high".

| type | required | default | | ---- | -------- | ------- | | enum | false | "low" |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

resizeHorizontal

Make the field resizeable in horizontal direction.

This works only when multiline is true.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

resizeVertical

Make the field resizeable in vertical direction.

This works only when multiline is true.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

Email

Use Email field to accept email addresses

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

Password

Use Password field for securely accepting secrets. It renders a toggle button to show/hide the password. You can override the toggle button using addOnEnd.

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

This will override the default show/hide toggle button

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

URL

Use URL field to accept or edit a URL

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

Numeric

Use Numeric field to accept numbers. The Numeric field renders an input element with type="text" & inputmode="numeric" to allow browsers to display an appropriate virtual keyboard. It also helps to eliminate some usability issues that comes with input with type="number".

For use cases of strictly speaking numbers like age, use Textfield component with type="number".

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

Search

Use Search field to accept search keywords.

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

Datefield

Use Datefield to work with dates.

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

Timefield

Use Timefield to select a time.

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon or text to render as start qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

qualifierEnd

Icon or text to render as end qualifier. Accepts SVG for icons.

| type | required | default | | ----- | -------- | ------- | | union | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

Pinfield

Use Pinfield for verification purposes, it can have numbers, alphabets, or characters as input but comes with the numeric keyboard. Pinfield allows 4 characters as input by default, but you can customize it using length prop as per your use case. Pinfield applies a placeholder value by default but you can override it using placeholder prop.

Props

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Field matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

qualifierStart

Icon to render as start qualifier, accepts SVG.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

qualifierEnd

Icon to render as end qualifier, accepts SVG.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnStart

React node to render before the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

addOnEnd

React node to render after the field content.

| type | required | default | | ------- | -------- | ------- | | element | false | null |

swapSlots

Swap the slots for qualifiers and addOns.

| type | required | default | | ---- | -------- | ------- | | bool | false | N/A |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes the field disabled if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

length

Number of characters allowed in the field.

| type | required | default | | ------ | -------- | ------- | | number | false | 4 |

alignCenter

Aligns the input content in center.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

placeholder

Placeholder value to show in the field.

| type | required | default | | ------ | -------- | ------- | | string | false | "" |

InputWrapper

Use InputWrapper to wrap various building blocks.

Props

children

React node

| type | required | default | | ---- | -------- | ------- | | node | false | null |

size

Controls size of the input. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Input matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

shrink

Removes the spacing between its children.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

bezel

Adds padding in the container.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

disabled

Makes field non interactive.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

Input

Input renders a native input field.

Props

type

Type of input control.

| type | required | default | | ------ | -------- | ------- | | string | false | "text" |

size

Controls size of the input. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

stretch

Input matches the width of its container.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

invalid

Adds error styles to the field if true.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Makes field non interactive.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

enclosed

Add border on each sides

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

bezel

Adds padding on each sides

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

InputQualifier

InputQualifier provides a hint about the expected content of the field. They can be SVG icons or words.

Props

children

React node for the main content.

| type | required | default | | ---- | -------- | ------- | | node | true | N/A |

size

Controls size of the field. Accepts xs, s, m, l for extra small, small, medium & large.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

InputAddOn

InputAddOn can be used to add extra React nodes along with Input.

Props

children

React node for the main content.

| type | required | default | | ---- | -------- | ------- | | node | true | N/A |

useInput

React hook which returns prop getter functions. Use these functions to generate prop objects for different building blocks.

Arguments

useInput accepts the following props:

1. size
2. invalid
3. disabled
4. stretch
5. qualifierStart
6. qualifierEnd
7. addOnStart
8. addOnEnd
9. swapSlots

Getter functions

getWrapperProps()

Use this function to create props for InputWrapper component.

const { getWrapperProps } = useInput({ size: "m", invalid: false, disabled: false, stretch: true });

<InputWrapper {...getWrapperProps()}>
  /* contents of InputWrapper */
</InputWrapper>

getInputProps()

Use this function to create props for Input component.

const { getInputProps } = useInput({ size: "m", invalid: false, disabled: false, stretch: true });

<InputWrapper>
  <Input
    {...getInputProps()}
  />
  /* rest of the contents */
</InputWrapper>

getQualifierProps()

Use this function to create props for InputQualifier component.

const { getQualifierProps } = useInput({ size: "m" });

<InputWrapper>
  <InputQualifier
    {...getQualifierProps()}
  />
  /* rest of the contents */
</InputWrapper>

getStartSlots()

Use this function to handle qualifiers and addOns attached to the start of the field. This function comes in handy when you create a new input field using the unit components like InputWrapper and Input as it handles the order of the elements attached. getStartSlots() accepts two arguments:

• qualifierProps: a props object to pass on to the qualifier
• addOnProps: a props object to pass on to the addOn

const { getStartSlots } = useInput({
    qualifierStart: <IconPlaceholder />,
    addOnStart: <Button>action</Button>,
    swapSlots: false,
  });

  <InputWrapper>
    <>{getStartSlots({ qualifierProps: { ariaLabel: "qualifier" } })}</>
    <Input />
  </InputWrapper>

getEndSlots()

Use this function to handle qualifiers and addOns attached to the end of the field. This function comes in handy when you create a new input field using the unit components like InputWrapper and Input as it handles the order of the elements attached. getEndSlots() accepts two arguments:

• qualifierProps: a props object to pass on to the qualifier
• addOnProps: a props object to pass on to the addOn

const { getEndSlots } = useInput({
    qualifierStart: <IconPlaceholder />,
    addOnStart: <Button>action</Button>,
    swapSlots: true,
  });

  <InputWrapper>
    <Input />
    <>{getEndSlots({ qualifierProps: { ariaLabel: "qualifier" } })}</>
  </InputWrapper>

The above code snipped will render the button (addOn) followed by the icon (qualifier) as swapSlots is true.