@asphalt-react/textfield
Version:
Textfield
1,292 lines (814 loc) • 28 kB
Markdown
Textfield
[](https://badge.fury.io/js/@asphalt-react%2Ftextfield)
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
```jsx
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
# 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.
```jsx
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](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation).
2. All textfields supports `data-/*` attributes & [DOM attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattr)
# Accessing through React ref
To get access to the underlying DOM element, pass a [React ref](https://reactjs.org/docs/refs-and-the-dom.html) 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](https://www.w3.org/TR/wai-aria-1.1/#input).
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.
```jsx
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.
```jsx
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.
```jsx
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
```jsx
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
```jsx
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.
[comment]: # "Textfield Props"
# 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
[comment]: # "Email Props"
# 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`.
[comment]: # "Password Props"
# 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
[comment]: # "URL Props"
# 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](https://html.spec.whatwg.org/multipage/input.html#when-number-is-not-appropriate) that comes with input with `type="number"`.
For use cases of strictly speaking numbers like age, use Textfield component with `type="number"`.
[comment]: # "Numeric Props"
# 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.
[comment]: # "Search Props"
# 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.
[comment]: # "Datefield Props"
# 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.
[comment]: # "Timefield Props"
# 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.
[comment]: # "Pinfield Props"
# 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 | "" |
PhoneNumber
Use Phone Number field to accept phone number.
[comment]: # "PhoneNumber Props"
# 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 |
| ------ | -------- | ------- |
| string | 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.
```js
{
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
```js
({countryCode, inputValue}, { event }) => {}
```
| type | required | default |
| ---- | -------- | ------- |
| func | false | N/A |
InputWrapper
Use InputWrapper to wrap various building blocks.
[comment]: # "InputWrapper Props"
# 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 |
Input
Input renders a native input field.
[comment]: # "Input Props"
# 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.
[comment]: # "InputQualifier Props"
# 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.
[comment]: # "InputAddOn Props"
# Props
## children
React node for the main content.
| type | required | default |
| ---- | -------- | ------- |
| node | true | N/A |