v2.0.4

Text Input

Stable

This component is considered stable. Reach out to the Spark team to find out more about what this means.

Open in Storybook Edit this page

Installation

Install yarn add @spark-web/text-input

npm @spark-web/text-input

Source GitHub.com

Bundle unpkg.com

Text input provides a way for inputting text. The component must be nested within a Field. See Field for more details.

Text Input

Controlled

A TextInput can be either controlled or uncontrolled. To control a TextInput provide a value, as well as an onChange function to set the new value when the select is updated.

Example controlled

The current value is: 1000000.101

Open in Playroom

const [value, setValue] = React.useState(1000000.101);

return (
  <Stack gap="large">
    <Field label="Example controlled">
      <TextInput value={value} onChange={e => setValue(e.target.value)} />
    </Field>
    <Text>The current value is: {value}</Text>
  </Stack>
);

const [value, setValue] = React.useState(1000000.101);

return (
  <Stack gap="large">
    <Field label="Example controlled">
      <TextInput value={value} onChange={e => setValue(e.target.value)} />
    </Field>
    <Text>The current value is: {value}</Text>
  </Stack>
);

Uncontrolled

A TextInput can also be uncontrolled, managing it's own internal state. To access the value, instead of writing an onChange handler, you would use a ref to get form values from the DOM.

Example uncontrolled

The input value is:

Open in Playroom

const inputRef = React.useRef(null);
const [value, setValue] = React.useState('');
const showValueHandler = React.useCallback(() => {
  setValue(inputRef.current?.value);
}, [setValue]);

return (
  <Stack gap="large">
    <Field label="Example uncontrolled">
      <FloatInput ref={inputRef} />
    </Field>
    <Button onClick={showValueHandler}>Show input value</Button>
    <Text>The input value is: {value}</Text>
  </Stack>
);

const inputRef = React.useRef(null);
const [value, setValue] = React.useState('');
const showValueHandler = React.useCallback(() => {
  setValue(inputRef.current?.value);
}, [setValue]);

return (
  <Stack gap="large">
    <Field label="Example uncontrolled">
      <FloatInput ref={inputRef} />
    </Field>
    <Button onClick={showValueHandler}>Show input value</Button>
    <Text>The input value is: {value}</Text>
  </Stack>
);

Input Adornments

You can also add adornments to the TextInput component (at the start or end).

Example

The current value is: 10000.101

Open in Playroom

const [value, setValue] = React.useState(10000.101);

return (
  <Stack gap="large">
    <Field label="Example">
      <TextInput type="numeric" onChange={e => setValue(e.target.value)}>
        <InputAdornment placement="start">
          <Text>~</Text>
        </InputAdornment>
        <InputAdornment placement="end">
          <Text>%</Text>
        </InputAdornment>
      </TextInput>
    </Field>
    <Text>The current value is: {value}</Text>
  </Stack>
);

const [value, setValue] = React.useState(10000.101);

return (
  <Stack gap="large">
    <Field label="Example">
      <TextInput type="numeric" onChange={e => setValue(e.target.value)}>
        <InputAdornment placement="start">
          <Text>~</Text>
        </InputAdornment>
        <InputAdornment placement="end">
          <Text>%</Text>
        </InputAdornment>
      </TextInput>
    </Field>
    <Text>The current value is: {value}</Text>
  </Stack>
);

InputContainer

The InputContainer is used internally to handle some shared styling between components that are wrapped in the Field component.

Typically input adornments (icons or buttons that appear to be inside the input) will be absolutely positioning above it and padding is applied to make sure that text does not get obscured below the adornments.

On top of this, password managers will insert buttons above the input which can get in the way of our adornments.

To get around these problems, we wrap the input and adornments with the InputContainer and apply our own focus styles to an absolutely positioned element that is an adjacent sibling of the input (when the input is focused).

The InputContainer also provides the border and background styles and has slots to place the start and end adornments.

Props

TextInput

Prop	Type	Description
children?	AdornmentsAsChildren: ReactElement<InputAdornmentProps, string \| JSXElementConstructor<any>> \| [ReactElement<InputAdornmentProps, string \| JSXElementConstructor<any>>, ReactElement<InputAdornmentProps, string \| JSXElementConstructor<...>>]	Adorn the input with ornamental element(s) to aid user input, or interactive element(s) to augment user input. Each child must be wrapped with the `InputAdornment` component to ensure proper layout, otherwise it will not be rendered.
data?	DataAttributeMap	Sets data attributes for the element.
inputMode?	ValidModes: "text" \| "none" \| "email" \| "search" \| "tel" \| "url" \| "numeric" \| "decimal"	Sets the input mode attribute for the component.
type?	ValidTypes: "number" \| "text" \| "password" \| "email" \| "search" \| "tel" \| "url"	How an input behaves varies considerably depending on the value of its type attribute. If this attribute is not specified, the default type "text".

InputContainer

Prop	Type	Description
alignItems?	ResponsiveProp<"start" \| "end" \| "center" \| "stretch">	Controls the alignment of items on the cross axis.
alignSelf?	ResponsiveProp<"start" \| "end" \| "center" \| "stretch">	Overrides the parent's `align-items` value. Controls the alignment of item's on the cross axis.
border?	ResponsiveProp<"neutral" \| "standard" \| "standardInverted" \| "field" \| "fieldHover" \| "fieldAccent" \| "fieldDisabled" \| "primary" \| "primaryHover" \| "primaryActive" \| "secondary" \| "secondaryHover" \| ... 10 more ... \| "positiveMuted">	The `border` property sets the color of an element's border.
borderBottom?	ResponsiveProp<"neutral" \| "standard" \| "standardInverted" \| "field" \| "fieldHover" \| "fieldAccent" \| "fieldDisabled" \| "primary" \| "primaryHover" \| "primaryActive" \| "secondary" \| "secondaryHover" \| ... 10 more ... \| "positiveMuted">	The `border` property sets the color of an element's border on the bottom side.
borderLeft?	ResponsiveProp<"neutral" \| "standard" \| "standardInverted" \| "field" \| "fieldHover" \| "fieldAccent" \| "fieldDisabled" \| "primary" \| "primaryHover" \| "primaryActive" \| "secondary" \| "secondaryHover" \| ... 10 more ... \| "positiveMuted">	The `border` property sets the color of an element's border on the left side.
borderRadius?	ResponsiveProp<"medium" \| "small" \| "large" \| "full">	The `borderRadius` property rounds the corners of an element's outer border edge.
borderRight?	ResponsiveProp<"neutral" \| "standard" \| "standardInverted" \| "field" \| "fieldHover" \| "fieldAccent" \| "fieldDisabled" \| "primary" \| "primaryHover" \| "primaryActive" \| "secondary" \| "secondaryHover" \| ... 10 more ... \| "positiveMuted">	The `border` property sets the color of an element's border on the right side.
borderTop?	ResponsiveProp<"neutral" \| "standard" \| "standardInverted" \| "field" \| "fieldHover" \| "fieldAccent" \| "fieldDisabled" \| "primary" \| "primaryHover" \| "primaryActive" \| "secondary" \| "secondaryHover" \| ... 10 more ... \| "positiveMuted">	The `border` property sets the color of an element's border on the top side.
borderWidth?	ResponsiveProp<"large" \| "standard">	The `borderWidth` property sets the width of an element's border.
bottom?	ResponsiveProp<0>: 0 \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", 0>>	The `bottom` property participates in setting the vertical position of a positioned element. It has no effect on non-positioned elements.
children?	ReactNode: string \| number \| false \| true \| {} \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal	Children element to be rendered inside the component.
className?	string	Custom css styles.
cursor?	"default" \| "pointer"	The `cursor` property sets the type of mouse cursor, if any, to show when the mouse pointer is over an element.
data?	DataAttributeMap	Sets data attributes on the component.
display?	ResponsiveProp<"flex" \| "none" \| "block" \| "inline" \| "inline-block" \| "inline-flex">	Sets whether an element is treated as a block or inline element and the layout used for its children.
endAdornment?	ReactElement<InputAdornmentProps, string \| JSXElementConstructor<any>>	Slot to end render adornment.
flex?	ResponsiveProp<0 \| 1>	The `flex` shorthand property sets how a flex item will grow or shrink to fit the space available in its flex container.
flexDirection?	ResponsiveProp<"row" \| "column" \| "rowReverse" \| "columnReverse">	Defines the main axis, or how the children are placed.
flexGrow?	ResponsiveProp<0 \| 1>	The `flexGrow` property sets the flex grow factor of a flex item main size.
flexShrink?	ResponsiveProp<0 \| 1>	The `flexShrink` property sets the flex shrink factor of a flex item. If the size of all flex items is larger than the flex container, items shrink to fit according to `flex-shrink`.
flexWrap?	ResponsiveProp<"nowrap" \| "wrap">	Allow flex items to flow onto multiple lines.
gap?	ResponsiveProp<"medium" \| "xsmall" \| "small" \| "large" \| "xxsmall" \| "xlarge" \| "xxlarge">	The size of the gap between each child element.
height?	ResponsiveSizing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "full" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "full">>	Sets the element's height.
id?	string	An identifier which must be unique in the whole document.
justifyContent?	ResponsiveProp<"start" \| "end" \| "center" \| "stretch" \| "spaceBetween">	defines how the browser distributes space between and around content items along the main-axis.
left?	ResponsiveProp<0>: 0 \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", 0>>	The `left` property participates in specifying the horizontal position of a positioned element. It has no effect on non-positioned elements.
margin?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `margin` shorthand property sets the margin area on all four sides of an element at once.
marginBottom?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `marginBottom` property sets the margin area on the bottom side of an element.
marginLeft?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `marginLeft` property sets the margin area on the left side of an element.
marginRight?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `marginRight` property sets the margin area on the right side of an element.
marginTop?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `marginTop` property sets the margin area on the top side of an element.
marginX?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `marginY` shorthand property sets the margin area on the left and right of the element.
marginY?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `marginY` shorthand property sets the margin area on the top and bottom of the element.
minHeight?	0	The `minHeight` property sets the minimum height of an element. It prevents the used value of the height property from becoming smaller than the value specified for `minHeight`.
minWidth?	0	The `minWidth` property sets the minimum width of an element. It prevents the used value of the width property from becoming smaller than the value specified for `minWidth`.
opacity?	ResponsiveProp<number>: number \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", number>>	Sets the opacity of the element. Opacity is the degree to which content behind an element is hidden, and is the opposite of transparency.
overflow?	"hidden" \| "scroll" \| "visible" \| "auto"	The `overflow` shorthand property sets the desired behavior for an element's overflow — i.e. when an element's content is too big to fit in its block formatting context — in both directions.
padding?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `padding` shorthand property sets the padding area on all four sides of an element at once.
paddingBottom?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `paddingBottom` property sets the height of the padding area on the bottom of an element.
paddingLeft?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `paddingLeft` property sets the width of the padding area on the left of an element.
paddingRight?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `paddingRight` property sets the width of the padding area on the right of an element.
paddingTop?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `paddingTop` property sets the height of the padding area on the top of an element.
paddingX?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `paddingX` shorthand property sets the padding area on the left and right of the element.
paddingY?	ResponsiveSpacing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "xlarge" \| "xxlarge">>	The `paddingY` shorthand property sets the padding area on the top and bottom of the element.
right?	ResponsiveProp<0>: 0 \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", 0>>	The `right` property participates in specifying the horizontal position of a positioned element. It has no effect on non-positioned elements.
shadow?	"medium" \| "small" \| "large"	The `boxShadow` property adds shadow effects around an element's frame.
startAdornment?	ReactElement<InputAdornmentProps, string \| JSXElementConstructor<any>>	Slot to start render adornment.
top?	ResponsiveProp<0>: 0 \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", 0>>	The `top` property participates in specifying the vertical position of a positioned element. It has no effect on non-positioned elements.
userSelect?	"none"	The `userSelect` property controls whether the user can select text.
width?	ResponsiveSizing: "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "full" \| Partial<Record<"mobile" \| "tablet" \| "desktop" \| "wide", "medium" \| "xsmall" \| "small" \| "large" \| "none" \| "xxsmall" \| "full">>	Sets the element's width.
zIndex?	ResponsiveProp<"dropdownBlanket" \| "dropdown" \| "sticky" \| "modalBlanket" \| "modal" \| "notification">	The `zIndex` property sets the "z-order" of a positioned element and its descendants or flex items. Overlapping elements with a larger z-index cover those with a smaller one.

Extra props are passed into the underlying Box component.