# salla-custom-fields (https://docs.salla.dev/twilight/react/web-components/salla-custom-fields)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

Renders a form of store-defined custom fields (text inputs and photo uploads) with a save button.
Use it on a profile or registration page for the fields the merchant added. Fields of type `photo`
render a `salla-file-upload`, every other type renders a native `<input>` of that `type`.
Submitting the form saves the values with the profile API (`salla.api.profile.updateCustomFields`).
Renders nothing when there are no fields. Each field has a `<label>` linked to its input, and a
required field shows a `*` after its label.

## Use it [#use-it]

In HTML or JSX, use the tag `<salla-custom-fields>` with the **Attribute** names below. In React, the wrapper takes the **Property** names (camelCase).

```tsx
import { SallaCustomFields } from '@salla.sa/twilight-components-react/custom-fields';
```

**Client-only.** On the server this wrapper renders a placeholder (a skeleton, or nothing), and the real component mounts in the browser. Do not rely on it for content that search engines must see.

## Example [#example]

```tsx
import { SallaCustomFields } from '@salla.sa/twilight-components-react/custom-fields';

export function Example() {
  return (
    <SallaCustomFields
      fields='[{"id":1,"label":"Company","type":"text","required":true,"value":""},{"id":2,"label":"ID photo","type":"photo"}]'
      fileUploadUrl="/upload" />
  );
}
```

```html
<salla-custom-fields
  fields='[{"id":1,"label":"Company","type":"text","required":true,"value":""},{"id":2,"label":"ID photo","type":"photo"}]'
  file-upload-url="/upload">
</salla-custom-fields>
```

## Properties [#properties]

| Property        | Attribute         | Description                                                                                                                                                                                                                                                                                                    | Type                      | Default |
| --------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------- |
| `fields`        | `fields`          | The list of custom fields to render. Accepts an array or a JSON string of an array of `{ id, label, type, required, value }` objects. `type` is `photo` for a file upload, otherwise it is used as the `type` of a native `<input>`. Read once when the component loads; use `setFields()` to change it later. | `CustomField[] \| string` |         |
| `fileUploadUrl` | `file-upload-url` | The URL to send file uploads to. **Deprecated:** Not read by the component, so it has no effect. It will be removed in the next major version.                                                                                                                                                                 | `string`                  |         |
| `isEditable`    | `is-editable`     | Whether the fields can be edited by the user. When `false`, the inputs, uploads and save button are disabled.                                                                                                                                                                                                  | `boolean`                 | `true`  |

## Events [#events]

Listen with `addEventListener`, or the `on` prop of the React wrapper (for example `onModalBack`).

| Event          | Description                                                                                                                                                     | Detail                                                             |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `fieldChanged` | Emitted when a text field's value changes. `event.detail` is `{ fieldId, value, isValid }`, where `isValid` is `false` if the field is required and now empty.  | `{ fieldId: string \| number; value: unknown; isValid: boolean; }` |
| `fileUploaded` | Emitted when a photo field adds a file or fails to. `event.detail` is `{ fieldId, file, isValid }`, where `isValid` is `false` if the upload reported an error. | `{ fieldId: string \| number; file: File; isValid: boolean; }`     |

## Methods [#methods]

Call these on the element or a React ref.

### `getFieldValues() => Promise<{ [key: string]: unknown; }>` [#getfieldvalues--promise-key-string-unknown-]

Gets the current values of all fields, formatted for submission.

Returns `Promise<{ [key: string]: unknown; }>`: Resolves to an object keyed `custom_fields[<field id>]` with each field's value.

### `setFields(fields: CustomField[]) => Promise<void>` [#setfieldsfields-customfield--promisevoid]

Replace the displayed fields.

| Parameter | Type            | Description                                                     |
| --------- | --------------- | --------------------------------------------------------------- |
| `fields`  | `CustomField[]` | The new list of fields, in the same shape as the `fields` prop. |

### `validateFields() => Promise<boolean>` [#validatefields--promiseboolean]

Validates all required fields and shows an error under each empty one.

Returns `Promise<boolean>`: Resolves to `true` if every required field has a value, otherwise `false`.

## Related [#related]

Renders: [`<salla-file-upload>`](https://docs.salla.dev/twilight/react/web-components/salla-file-upload), [`<salla-button>`](https://docs.salla.dev/twilight/react/web-components/salla-button).