@asphalt-react/textfield

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.