@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
• Phone Number
• Hero

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

• All textfields support HTML form validations.
• 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

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

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:

• size
• invalid
• disabled
• stretch
• qualifierStart
• qualifierEnd
• addOnStart
• addOnEnd
• 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.

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

bezel

Adds padding on each sides

type	required	default
bool	false	true

nude

Removes the background.

type	required	default
bool	false	false

underline

Displays only the bottom border as an underline.

type	required	default
bool	false	false

emphasize

Enables heading text.

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	""

bezel

Adds padding on each sides

type	required	default
bool	false	true

nude

Removes the background.

type	required	default
bool	false	false

underline

Displays only the bottom border as an underline.

type	required	default
bool	false	false

emphasize

Enables heading text.

type	required	default
bool	false	false

PhoneNumber

Use Phone Number field to accept phone number.

Props

size

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

type	required	default
enum	false	"m"

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

stretch

Field matches the width of its container.

type	required	default
bool	false	false

emptyResult

Show custom node when no result is found.

type	required	default
node	false	N/A

placeholder

Hint text to show in input field.

type	required	default
string	false	N/A

searchPlaceholder

Hint text to show in search input field.

type	required	default
string	false	"Search Country"

showFlag

Show country flag in option and button.

type	required	default
bool	false	false

countries

Array of country objects.

{
   id: "+62",
   name: "Indonesia",
   flag: "https://www.url.co.id/indonesia-flag.svg"
   initialSelected: false     // true if this item should be initially selected
}

Out of the above id and name is required.

type	required	default
arrayOf	false	N/A

defaultCountry

Add default country. By add this props the selection will disabled.

type	required	default
string	false	""

onChange

Callback to handle the country selection and input field. It has the following signature

• countryCode - country code selected by user interaction
• inputValue - input value from user

 ({countryCode, inputValue}, { event }) => {}

type	required	default
func	false	N/A

bezel

Adds padding on each sides

type	required	default
bool	false	true

nude

Removes the background.

type	required	default
bool	false	false

underline

Displays only the bottom border as an underline.

type	required	default
bool	false	false

emphasize

Enables heading text.

type	required	default
bool	false	false

separator

Enables separator.

type	required	default
bool	false	true

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

hasEndSlot

Set this props to true if stretch is true and there is a qualifier/addOn at the end.

type	required	default
bool	false	false

nude

Removes the background.

type	required	default
bool	false	false

underline

Displays only the bottom border as an underline.

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

nude

Removes the background.

type	required	default
bool	false	false

underline

Displays only the bottom border as an underline.

type	required	default
bool	false	false

emphasize

Enables heading text.

type	required	default
bool	false	false

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

Hero

Use Hero for transactional inputs such as payments, transfers, and similar financial interactions.

Props

size

Size of the Hero input.

type	required	default
enum	false	"m"

invalid

Adds error styles to the field if true.

type	required	default
bool	false	false

stretch

Field matches the width of its container.

type	required	default
bool	false	false

disabled

Makes the field disabled if true.

type	required	default
bool	false	false

align

Aligns the text inside the input.

type	required	default
enum	false	"left"

label

Text for the label.

type	required	default
string	false	""

qualifierStart

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

type	required	default
union	false	N/A

qualifierEnd

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

type	required	default
union	false	N/A

addOnStart

React node to render before the field content.

type	required	default
element	false	N/A

addOnEnd

React node to render after the field content.

type	required	default
element	false	N/A

placeholder

Placeholder text for the input.

type	required	default
string	false	""

prefix

Adds a prefix to the input.

When using a prefix, combine it with the mask prop to control which characters are allowed.

type	required	default
string	false	""

mask

Applies an input mask to restrict allowed characters. The default value is an alphanumeric mask of length 12 based on the common case for phone.

Mask tokens:

• 9 → numeric (0–9)
• a → alphabetic (A–Z, a–z)
• * → any character (allows all characters)

The mask length is determined by repeating tokens. For example, "99999999" allows eight digits, while "****" allows four any characters.

type	required	default
string	false	"**************"

pin

Enables pin placeholder.

type	required	default
bool	false	false