Implementing a Custom Form Field

Docs

Search

Help & Feedback

Sign In

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Authors:

Cameron Johns, Cille Schliebitz, Anita Gu

Changed on:

3 Feb 2025

Overview

This lesson walks through the implementation of a custom form field component for a Stock Reservation user action. We'll build a field that captures

`locationRef`

and

`quantity`

and outputs a JSON object structured as required by the Ruleset. The lesson covers configuring the user action button, creating the custom field component using React Function Components and the

`FormFieldProps`

interface, registering the field, and updating the workflow definition to use the new custom field type.

Key points

User Action Configuration: Enabling user actions in the manifest is a prerequisite for testing the custom field.
```
`StockReservation`
```
Data Structure: The custom field will capture data in a specific JSON format: { "locationRef": "F_NSYD", "quantity": 1 }.
React Function Component: The custom field is implemented as a React Function Component (FC).
```
`FormFieldProps`
```
Interface: The component uses the
```
`FormFieldProps`
```
interface from the UX Framework, typed with the output payload structure.
```
`onChange`
```
Handler: The
```
`onChange`
```
property of
```
`FormFieldProps`
```
is used to capture user input.
Field Registration: The custom field is registered with the
```
`FieldRegistry`
```
using a specific name.
Workflow Update: The workflow user action definition is updated to use the new custom field type.
Testing: The lesson includes steps to verify that the custom field is correctly rendered in the user action form.

In this lesson, you will implement a new custom field component for a Stock Reservation user action.

Training Accounts have been prepared to cater for this use case

We have prepared the Training Accounts to cater for this use case.
The PRODUCT_CATALOGUE MASTER workflow contains a

`StockReservationRequest`

Ruleset with a User Action. It expects an Event Attribute type of

`stockReservation`

, which you will implement a custom field for to support.
This Ruleset will post a SoftReserve event to the INVENTORY_CATALOG DEFAULT workflow, which will create a soft reserve inventory quantity, recalculate Stock on Hand, and set an expiry on the reservation.

The Ruleset expects an Event Attribute named "

`stockReservation`

" containing 2 fields:

`locationRef`

and

`quantity. `

It also expects a JSON value with a similar structure to the one below:

`{`

`  "locationRef": "F_NSYD",`

`  "quantity": 1`

`}`

You will build a field to produce this value for the "

`stockReservation`

" attribute on the posted Event.

To start with, let's simply create a "Hello Field" example:

Before you begin creating your field, let's make sure the User Action button is working on the page. Since you are building upon the screen created in the UX Framework course, it is likely that this User Action is not yet configured to show in the Manifest.

Modify the fragment manifest, and enable User Actions by adding the

`actions`

property to the

`props`

for the Product Availability Detail Page:

`"props": {`

`  "title": "Product Availability",`

`  "actions": {`

`    "enabled": true`

`  }`

`}`

Check that you now see a "RESERVE" button on the top right of the Availability Screen, as per the video below.

The video below shows how the initial user action is configured and the reservationDetails attribute is typed as "STRING".

Create a new
```
`StockReservation.tsx`
```
and define the interface for the outgoing payload. [0:50]
You now need to define the Field component by once again using the
```
`FC`
```
(FunctionComponent) component from React as the base, and typing it to the UX Framework
```
`FormFieldProps`
```
— which in turn requires another generic for the output, in our case we will define it to be our payload structure
```
`StockReservationPayload`
```
. [1:43]
The FormFieldProps provides a number of useful properties — use the
```
`onChange`
```
since this will allow us to capture the user input. [2:36]

Field Components call onChange whenever the field state changes

Field Components should call

`onChange`

whenever the field state changes. This will cause a re-render, so best to wrap it in a

`useEffect`

to avoid undesired infinite loops.

Before you go implement the full function of the component, let's make sure it renders to screen by simply returning a "Hello Form" div. [3:01]
Register the field with the
```
`FieldRegistry`
```
, and take note of the name. This will be used to configure the workflow later. [3:29]
Make sure the local references include a dot slash:
```
`'./fields/StockReservation';`
```
[4:02]
Update the workflow user action definition to change the type from
```
`STRING`
```
to
```
`stockReservation`
```
. [4:13]

Training Account workflows have "stockReservation" references

Training Account workflows already reference "

`stockReservation`

" as the Event Attribute type.

Click the drop down list to see the other Workflow lists

To locate the PRODUCT CATALOGUE workflow, click on the drop down list where it says CONTROL GROUP to see the other Workflow lists, and select PRODUCT CATALOGUE:

Once complete, open the user action form, and you should see the "Hello Form" text, indicating that the UX Framework has successfully mapped your custom field component to the attribute type defined in the workflow.

Hello Field

This video explains how to create a custom field

Cameron Johns

Contributors:

Knowledge Tracks Related To This Topic

Component SDK

Extending the UX Framework with the Component SDK

Building Custom Components with the Component SDK

Setting Up Your Component SDK Project

Client Scenario: Building a Product Availability Map

Creating and Registering a Custom Component

Configuring Custom Components via the Manifest

Accessing User and Location Context with the useAuth Hook

Integrating a Third-Party Map Component

Adding Nested (Child) Components

Accessing Page Query Data

Style and Theme Your Component

Make Your Component Interactive

Configuring Components with Settings

Configuring Components with Dynamic Attributes

Extending Forms with Custom Field Components

Implementing a Custom Form Field

Enhance Your Custom Fields: Leveraging Existing Components from the Registry

Fetching Data with the useQuery Hook

Completing the Custom Form Field: Outputting the Result

Creating Custom Template Helpers

Unit Testing Custom Components

Deploying a Custom Component Plugin

Copyright © 2025 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.

Implementing a Custom Form Field

Overview

Key points

To start with, let's simply create a "Hello Field" example:

Hello Field

Cameron Johns

Contributors:

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links