Documentation
Discussions

useConfigurator()

Hook used within the ConfiguratorProvider context, which allows us to retrieve and set product configuration

This component is key to the whole experience of using the Composable Configurator. It serves the function of retrieving the configuration details for a given item, and provides the means to change that configuration with a setConfiguration method.

This hook can only be used within a context.

Prop List

NameTypeStatus
assetIdStringRequired
keyStringRequired

assetId: String - Required

This is the assetId of the item you wish to load the configuration data for.

key: String - Required

This is a means to provide a unique identifier for each item loaded, in order to ensure you can distinguish between copies of the same product being loaded multiple times. This enables us to call the useConfigurator hook in multiple components within the same ConfiguratorProvider, and affect the same state variable.

In a simple example you could use the assetId string for both the assetId as well as the key properties.

Example

const product = useConfigurator({
  assetId: "3f8684ed-785f-4862-93bf-af7eeaaab961",
  key: "3f8684ed-785f-4862-93bf-af7eeaaab961",
});

Return Value

The return value in case of a successful load of data from the given assetId will be in the form of an object that looks kind of like this:

{
    "assetId": "3f8684ed-785f-4862-93bf-af7eeaaab961",
    "name": "Chair",
    "metadata": {
        "itemCode": "AubreyChair",
        "Type": "CHAIR"
    },
    "attributes": [
        {
            "id": "135cea22-7fb5-4c12-84ee-2a48e6921431",
            "name": "Fabric",
            "visible": true,
            "enabled": true,
            "metadata": {},
            "type": "Asset",
            "assetType": "item",
            "defaultValue": {
                "assetId": "7e9a44eb-13d0-4e77-9c74-9d805c150ac8",
                "type": "item"
            },
            "values": [
                {
                    "type": "item",
                    "assetId": "e1e9e564-7c3a-46a0-a114-bed6230f066b",
                    "name": "Microfiber Green",
                    "fileSize": 0,
                    "metadata": {},
                    "tags": [
                        "material",
                        "fabric",
                        "microfiber"
                    ],
                    "tagids": [
                        "8953f0f2-68b6-4298-a398-a837e2832284",
                        "139ebc5f-2267-4780-9cfd-1f4529b15d6c",
                        "e0c69ded-8016-40d8-aff9-11b27556522b"
                    ],
                    "pricing": null,
                    "visible": false,
                    "enabled": true,
                    "selected": false
                },
                {
                    "type": "item",
                    "assetId": "17c48830-a6f6-4f01-9459-8be9cab760fd",
                    "name": "Microfiber Purple",
                    "fileSize": 0,
                    "metadata": {},
                    "tags": [
                        "material",
                        "fabric",
                        "microfiber"
                    ],
                    "tagids": [
                        "8953f0f2-68b6-4298-a398-a837e2832284",
                        "139ebc5f-2267-4780-9cfd-1f4529b15d6c",
                        "e0c69ded-8016-40d8-aff9-11b27556522b"
                    ],
                    "pricing": null,
                    "visible": false,
                    "enabled": true,
                    "selected": false
                },
                {
                    "type": "item",
                    "assetId": "319635b7-735b-437c-b4ec-4e28789f89a2",
                    "name": "Cotton Blue",
                    "fileSize": 2745479,
                    "metadata": {},
                    "tags": [
                        "material",
                        "fabric",
                        "cotton"
                    ],
                    "tagids": [
                        "8953f0f2-68b6-4298-a398-a837e2832284",
                        "139ebc5f-2267-4780-9cfd-1f4529b15d6c",
                        "af4dcf63-04e3-43e2-be82-821d34672591"
                    ],
                    "pricing": null,
                    "visible": true,
                    "enabled": true,
                    "selected": false
                },
                {
                    "type": "item",
                    "assetId": "7e9a44eb-13d0-4e77-9c74-9d805c150ac8",
                    "name": "Cotton Red",
                    "fileSize": 2325423,
                    "metadata": {
                        "Name": "Red",
                        "Family": "Cotton"
                    },
                    "tags": [
                        "material",
                        "fabric",
                        "cotton"
                    ],
                    "tagids": [
                        "8953f0f2-68b6-4298-a398-a837e2832284",
                        "139ebc5f-2267-4780-9cfd-1f4529b15d6c",
                        "af4dcf63-04e3-43e2-be82-821d34672591"
                    ],
                    "pricing": null,
                    "visible": true,
                    "enabled": true,
                    "selected": true
                }
            ],
            "value": {
                "type": "item",
                "assetId": "7e9a44eb-13d0-4e77-9c74-9d805c150ac8",
                "name": "Cotton Red",
                "fileSize": 2325423,
                "metadata": {
                    "Name": "Red",
                    "Family": "Cotton"
                },
                "tags": [
                    "material",
                    "fabric",
                    "cotton"
                ],
                "tagids": [
                    "8953f0f2-68b6-4298-a398-a837e2832284",
                    "139ebc5f-2267-4780-9cfd-1f4529b15d6c",
                    "af4dcf63-04e3-43e2-be82-821d34672591"
                ],
                "pricing": null,
                "visible": true,
                "enabled": true
            }
        },
        {
            "id": "561cf10b-3cf1-4cd8-8718-43d7890dda4e",
            "name": "Legs",
            "visible": true,
            "enabled": true,
            "metadata": {},
            "type": "Asset",
            "assetType": "item",
            "defaultValue": {
                "assetId": "7dd1c8a9-e0e0-4a22-8e3c-a29a37a6d68e",
                "type": "item"
            },
            "values": [
                {
                    "type": "item",
                    "assetId": "874c48a4-b986-4024-8209-04ab8ca56682",
                    "name": "Wood Maple",
                    "fileSize": 502612,
                    "metadata": {},
                    "tags": [
                        "material",
                        "wood",
                        "legs-material"
                    ],
                    "tagids": [
                        "8953f0f2-68b6-4298-a398-a837e2832284",
                        "2aa8b8cb-188f-47b7-90ca-bc3481e92a96",
                        "1b982268-5b0f-41c7-809e-6884de484be3"
                    ],
                    "pricing": null,
                    "visible": true,
                    "enabled": true,
                    "selected": false
                },
                {
                    "type": "item",
                    "assetId": "7dd1c8a9-e0e0-4a22-8e3c-a29a37a6d68e",
                    "name": "Wood Walnut",
                    "fileSize": 400848,
                    "metadata": {},
                    "tags": [
                        "material",
                        "wood",
                        "legs-material"
                    ],
                    "tagids": [
                        "8953f0f2-68b6-4298-a398-a837e2832284",
                        "2aa8b8cb-188f-47b7-90ca-bc3481e92a96",
                        "1b982268-5b0f-41c7-809e-6884de484be3"
                    ],
                    "pricing": null,
                    "visible": true,
                    "enabled": true,
                    "selected": true
                }
            ],
            "value": {
                "type": "item",
                "assetId": "7dd1c8a9-e0e0-4a22-8e3c-a29a37a6d68e",
                "name": "Wood Walnut",
                "fileSize": 400848,
                "metadata": {},
                "tags": [
                    "material",
                    "wood",
                    "legs-material"
                ],
                "tagids": [
                    "8953f0f2-68b6-4298-a398-a837e2832284",
                    "2aa8b8cb-188f-47b7-90ca-bc3481e92a96",
                    "1b982268-5b0f-41c7-809e-6884de484be3"
                ],
                "pricing": null,
                "visible": true,
                "enabled": true
            }
        }
    ],
    "price": null,
    "configuration": {
        "Fabric": {
            "configuration": {},
            "assetId": "7e9a44eb-13d0-4e77-9c74-9d805c150ac8",
            "type": "item"
        },
        "Legs": {
            "configuration": {},
            "assetId": "7dd1c8a9-e0e0-4a22-8e3c-a29a37a6d68e",
            "type": "item"
        }
    }
}

🚧

Warning!

The type definition of this return is rather complex, as not all attribute types share the same properties. In practice you will find that TypeScript may get confused with trying to determine the presence of some of these properties on the return object.

You will need to rely on Type Guards or Type Assertions in order to get around this issue.

Setting the Configuration

In order to change the configuration on the product we need to use the setConfiguration() method.

setConfiguration(props: Configuration)

In practice, you will be setting the configuration to entries from the attribute values array read from the result listed above, for the given attribute name.

Example

In the return example above we see that the Fabric attribute is currently set to assetId "7e9a44eb-13d0-4e77-9c74-9d805c150ac8", which represents Cotton Red.

If we wanted to change the Fabric to Microfiber Green, we would need to do something like the following:

const fabric = product?.attributes?.find(
  (attr) => attr.name === "Fabric"
) as any;
if ("values" in fabric) {
  product.setConfiguration({
    Fabric: fabric.values.find(
      (value: { name: string }) => value.name === "Microfiber Green"
    ),
  });
}

Note that in this case I need to check if the values property exists inside the found attribute, since not all attribute types may have a values property.