Skip to main content

Composition vs Props API

You may have noticed that Atomic Elements has two APIs for building forms. For example, there are the TextField and TextInput components, both of which render a text input field.

The distinction is that TextField is part of the composition API, while TextInput is a wrapper around TextField that provides a more specific layout and customization via props. This allows developers to choose the approach that best fits their needs, whether they require more control over the layout or prefer a more straightforward, opinionated component.

Composition API​

The composition API is designed to be flexible and to support a wide variety of use cases. With this API, you are in control of the markup and layout of the field, while the TextField component handles the details of managing the input and accessibility. This approach is particularly useful when you need to create custom form fields that do not fit the standard patterns provided by the props API.

For example, you could use the TextField component to create a field with a message below the input, rather than above. This level of customization allows you to tailor the user interface to better match your application's design requirements:

<TextField value="" onChange={() => {}}>
  <Label>Label</Label>
  <Input />
  <Message>Message</Message>
</TextField>

Message

Or you could use the TextField component to create a field with a button and input.

<TextField value="" onChange={() => {}}>
  <Label>Label</Label>
  <Message>Message</Message>
  <Group isMerged>
    <Input />
    <Button variant="border">Save</Button>
  </Group>
</TextField>

Message

Props API​

The props API is designed to be more specific and to provide a more opinionated layout and customization. For example, the TextInput component is a wrapper around TextField that provides a more specific layout and customization is handled via props. This makes it easier to quickly create form fields with a consistent look and feel, without having to manually manage the layout and markup.

<TextInput
  label="Label"
  message="Message"
  size="full"
/>

Message

tip

In general, you will probably want to reach for the props API first. It is more opinionated and will likely cover most use cases. However, if you need more control over the layout and appearance of the field, the composition API is there for you.