@asphalt-react/textfield
v2.0.0
Published
Textfield
Downloads
357
Readme
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
- 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
- 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 withinvalid
prop set to true. - 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 |
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 |
stretchClass
Custom stretch class name.
| type | required | default | | ------ | -------- | ------- | | string | false | N/A |
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:
- 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.