Text Input

View on MongoDB.design

Installation

Yarn

yarn add @leafygreen-ui/text-input

NPM

npm install @leafygreen-ui/text-input

Peer Dependencies

| Package | Version | | ------------------------------------ | -------- | | @leafygreen-ui/leafygreen-provider | ^1.1.0 |

Example

import TextInput from '@leafygreen-ui/text-input';

const [value, setValue] = useState('');

return (
  <TextInput
    label="Email"
    description="Enter your email below"
    placeholder="[email protected]"
    onChange={event => {
      /* Something to handle the change event */
    }}
    value={value}
  />
);

Properties

| Prop | Type | Description | Default | | ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | id | string | id associated with the TextInput component. | | | label | string | Text shown in bold above the input element. | | | description | string | Text that gives more detail about the requirements for the input. | | | optional | boolean | Marks the input as optional | false | | disabled | boolean | Disabled the input | false | | onChange | function | The event handler function for the 'onchange' event. Accepts the change event object as its argument and returns nothing. | | | onBlur | function | The event handler function for the 'onblur' event. Accepts the focus event object as its argument and returns nothing. | | | placeholder | string | The placeholder text shown in the input field before the user begins typing. | | | errorMessage | string | Text that gives more detail about the requirements for the input. | 'This input needs your attention' | | successMessage | string | Text that indicates that the requirements for the input are met. | 'Success' | | state | 'none', 'valid', 'error' | Describes the state of the TextInput element before and after the input has been validated | 'none' | | value | string | Sets the HTML value attribute. | '' | | className | string | Adds a className to the class attribute. | '' | | type | 'email', 'password', 'search', 'text', 'url', 'tel', 'number' | Sets type for TextInput | 'text' | | darkMode | boolean | Determines whether or not the component will appear in dark mode. | false | | sizeVariant | 'xsmall', 'small', 'default', 'large', | Sets the side padding, text size, and input height. | default | | baseFontSize | 14, 16 | Determines the base font-size of the component if the sizeVariant prop is set to default | 14 | | ... | native input attributes | Any other props will be spread on the root input element | |

Special Case: Aria Labels

Either label or aria-labelledby must be provided a string, or there will be a console error. This is to ensure that screenreaders have a description for what the Text Input does.

Test Harnesses

getTestUtils()

getTestUtils() is a util that allows consumers to reliably interact with LG TextInput in a product test suite. If the TextInput component cannot be found, an error will be thrown.

Usage

import TextInput, { getTestUtils } from '@leafygreen-ui/text-input';

const utils = getTestUtils(lgId?: string); // lgId refers to the custom `data-lgid` attribute passed to `TextInput`. It defaults to 'lg-text_input' if left empty.

Single TextInput

import { render } from '@testing-library/react';
import TextInput, { getTestUtils } from '@leafygreen-ui/text-input';

...

test('text-input', () => {
  render(<TextInput label="label" value="text input" />);
  const { getInput, getInputValue } = getTestUtils();

  expect(getInput()).toBeInTheDocument();
  expect(getInputValue()).toBe('text input');
});

Multiple TextInput's

When testing multiple TextInput's it is recommended to add the custom data-lgid attribute to each TextInput.

import { render } from '@testing-library/react';
import TextInput, { getTestUtils } from '@leafygreen-ui/text-input';

...

test('text-input', () => {
  render(
    <>
      <TextInput data-lgid="text-input-1" label="label 1" />
      <TextInput data-lgid="text-input-2" label="label 2" value="text input" />
    </>,
  );
  const utilsOne = getTestUtils('text-input-1'); // data-lgid
  const utilsTwo = getTestUtils('text-input-2'); // data-lgid

  // First TextInput
  expect(utilsOne.getInput()).toBeInTheDocument();
  expect(utilsOne.getInputValue()).toBe('');

  // Second TextInput
  expect(utilsTwo.getInput()).toBeInTheDocument();
  expect(utilsTwo.getInputValue()).toBe('text input');
});

TextInput with other LG form elements

import { render } from '@testing-library/react';
import Toggle, { getTestUtils as getToggleTestUtils } from '@leafygreen-ui/toggle';
import TextInput, { getTestUtils as getTextInputTestUtils } from '@leafygreen-ui/text-input';
import TextArea, { getTestUtils as getTextAreaTestUtils } from '@leafygreen-ui/text-area';

...

test('Form', () => {
  render(
    <Form>
      <Toggle aria-label="Toggle label" />
      <TextInput label="TextInput label" />
      <TextArea label="TextArea label" />
    </Form>,
  );
  const toggleInputUtils = getToggleTestUtils();
  const textInputUtils = getTextInputTestUtils();
  const textAreaUtils = getTextAreaTestUtils();

  // LG Toggle
  expect(toggleInputUtils.getInput()).toBeInTheDocument();
  expect(toggleInputUtils.getInputValue()).toBe('false');

  // LG TextInput
  expect(textInputUtils.getInput()).toBeInTheDocument();
  expect(textInputUtils.getInputValue()).toBe('');

  // LG TextArea
  expect(textAreaUtils.getInput()).toBeInTheDocument();
  expect(textAreaUtils.getInputValue()).toBe('');
});

Test Utils

const {
  getInput,
  getLabel,
  getDescription,
  getErrorMessage,
  getInputValue,
  isDisabled,
  isValid,
  isError,
  isOptional,
} = getTestUtils();

| Util | Description | Returns | | ----------------- | ------------------------------------------ | ----------------------------- | | getInput | Returns the input node | HTMLButtonElement | | getLabel | Returns the label node | HTMLButtonElement | null | | getDescription | Returns the description node | HTMLButtonElement | null | | getErrorMessage | Returns the error message node | HTMLButtonElement | null | | getInputValue | Returns the input value | string | | isDisabled | Returns whether the input is disabled | boolean | | isValid | Returns whether the input state is valid | boolean | | isError | Returns whether the input state is error | boolean | | isOptional | Returns whether the input is optional | boolean |