> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joyfill.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Field Settings

## What Are Field Settings?

Field settings allow you to customize the form builder interface by:

* **Adding custom controls** for data collection
* **Hiding unnecessary options** to simplify the interface
* **Creating targeted settings** for different field types
* **Collecting metadata** for your business needs

## Quick Start

```jsx theme={null}
import { JoyDoc } from '@joyfill/components';

function MyForm() {
  const fieldSettings = {
    // Your custom settings go here
  };

  return (
    <JoyDoc
      doc={yourDocument}
      mode="edit"
      fieldSettings={fieldSettings}
    />
  );
}
```

## Understanding Targets

Targets determine **where** your settings appear in the form builder:

| Target                                | Scope               | Example Use Case                       |
| ------------------------------------- | ------------------- | -------------------------------------- |
| `file`                                | Entire document     | Document metadata, global settings     |
| `page`                                | Specific page       | Page sections, completion requirements |
| `field`                               | All field types     | Universal field behavior               |
| `text`, `number`, `dropdown`, `table` | Specific field type | Type-specific settings                 |
| `field_12345`                         | Individual field    | Custom field requirements              |

## Setting Types

### 1. Identifier Settings

Predefined field identifier options with custom option support:

```jsx theme={null}
identifier: {
  label: 'Identifier',  // Custom label
  options: [
    {
      title: 'Plain Identifier Option',
      description: 'Identifier details for text',
      value: 'customer_text_customidentifierselector'
    }
  ]
}
```

Sample output:

<img src="https://mintcdn.com/joyfill/UCng840bWYOmpI5x/images/docs/IdentifierSettings.png?fit=max&auto=format&n=UCng840bWYOmpI5x&q=85&s=d522c2414c11a95fdadef257e2b0b06b" alt="" width="1319" height="746" data-path="images/docs/IdentifierSettings.png" />

### 2. Metadata Settings

Custom controls that save data to field metadata:

| Type       | Use Case         | Properties                       |
| ---------- | ---------------- | -------------------------------- |
| `text`     | Short text       | `label`, `key`, `value`, `addon` |
| `textarea` | Long text        | `label`, `key`, `value`          |
| `number`   | Numeric values   | `label`, `key`, `value`, `addon` |
| `checkbox` | Yes/No options   | `label`, `key`, `value`          |
| `button`   | Actions          | `label`, `key`, `color`          |
| `divider`  | Visual separator | `key` only                       |

**Metadata Example:**

```jsx theme={null}
metadata: {
  options: [
    {
      type: FieldSettingsMetadataTypes.checkbox,
      label: 'Require Photo Uploads',
      description: 'Should a photo be required?',
      key: 'required'
    },
    {
      type: FieldSettingsMetadataTypes.number,
      label: 'Quantity',
      description: 'How many photos are required?',
      key: 'count'
    },
    {
      type: FieldSettingsMetadataTypes.divider,
      key: 'divider'
    },
    {
      type: FieldSettingsMetadataTypes.checkbox,
      label: 'Failing Option',
      key: 'fail'
    }
  ]
}
```

**Output:**

<img src="https://mintcdn.com/joyfill/UCng840bWYOmpI5x/images/docs/metadataSettings.png?fit=max&auto=format&n=UCng840bWYOmpI5x&q=85&s=f3d653ff2e0968acfe1d95f4f6792722" alt="" width="947" height="815" data-path="images/docs/metadataSettings.png" />

### 3. Table Columns Settings

Customize table field columns:

```jsx theme={null}
tableColumns: {
  types: ['text','dropdown', 'image', 'number' 'multiSelect', 'date', 'block', 'barcode','signature'],
  identifier: {
    label: 'Col Identifier',
    options: [
      {
        type: 'text',
        title: 'Deficiencies',
        description: 'Details about identifer for table',
        value: 'table_customidentifierselector'
      }
    ]
  },
  metadata: {
    options: [
      {
        type: 'number',
        label: 'Require Photo Col',
        description: 'Should a photo be required?',
        key: 'required'
      }
    ]
  },
  options: {
    metadata: {
      options: [
        {
          type: 'checkbox',
          label: 'Failing Option',
          description: 'Trigger deficiency capture.',
          key: 'failure'
        }
      ]
    }
  }
}
```

### **Metadata for columns:**

<img src="https://mintcdn.com/joyfill/UCng840bWYOmpI5x/images/docs/metadataForColumns.png?fit=max&auto=format&n=UCng840bWYOmpI5x&q=85&s=59df9ed457e95d7b990e3f06c88ca02d" alt="" width="367" height="178" data-path="images/docs/metadataForColumns.png" />

### Custom column identifier

<img src="https://mintcdn.com/joyfill/UCng840bWYOmpI5x/images/docs/customColumnIdentifier.png?fit=max&auto=format&n=UCng840bWYOmpI5x&q=85&s=c21c7334e8ce3a3c80bed16610aa3366" alt="" width="352" height="213" data-path="images/docs/customColumnIdentifier.png" />

### 4. Options Settings

Customize dropdown/select field options:

```jsx theme={null}
options: {
  metadata: {
    options: [
      {
        type: FieldSettingsMetadataTypes.checkbox,
        label: 'Failing Option',
        description: 'Trigger deficiency capture.',
        key: 'failure'
      }
    ]
  }
}
```

## Hiding Settings

Hide default settings by setting them to `false`:

```jsx theme={null}
const fieldSettings = {
  field: {
    title: false,        // Hide field title
    required: false,     // Hide required checkbox
    placeholder: false,  // Hide placeholder input
    styles: {
      fontSize: false,      // Hide font size
      fontColor: false,     // Hide font color
      backgroundColor: false // Hide background color
    }
  },
  page: {
    upload: false,      // Hide page background upload
    duplicate: false    // Hide page duplication
  }
};
```

## Advanced Features

### File Upload Handlers

```jsx theme={null}
onFileUploadAsync: async (params, fileUploads) => {
  console.log('onFileUploadAsync: ', params, fileUploads);
  return {
    _id: new Date().getTime(),
    url: 'https://s3.amazonaws.com/docspace.production.documents/6702de67c6ba43a423ca035f/documents/template_680bc498b6890a1324423764/680fbf96e97c7b42ec58f988-1745862550459.jpg'
  };
},
onFileClick: async (params, urlObject) => {
  console.log('onFileClick: ', params, urlObject);
},
onFileDelete: async (params, urlObject) => {
  console.log('onFileDelete: ', params, urlObject);
}
```

### Global Settings

```jsx theme={null}
const fieldSettings = {
  autoResize: false, // Set to true to see supported fields auto resize
  field: {
    systemFilePicker: false   // Disable system file picker
  }
};
```

## Complete Example

Here's the exact fieldSettings example from JoyDoc.stories.js:

```jsx theme={null}
import React, { useState } from "react";
import { JoyDoc } from "@joyfill/components";
import FieldSettingsMetadataTypes from "../constants/FieldSettingsMetadataTypes";
import fieldColumnTypes from "../constants/FieldTableColumnTypes";

function CompleteFieldSettingsExample() {
  const [document, setDocument] = useState(initialDocument);

  const fieldSettings = {
    autoResize: false, // Set to true to see supported fields auto resize
    page: {
      metadata: {
        options: [
          {
            type: FieldSettingsMetadataTypes.checkbox,
            label: "Require Photo",
            description: "Should a photo be required?",
            key: "required",
          },
        ],
      },
    },
    field: {
      systemFilePicker: false,
      onFileUploadAsync: async (params, fileUploads) => {
        console.log("onFileUploadAsync: ", params, fileUploads);
        return {
          _id: new Date().getTime(),
          url: "https://s3.amazonaws.com/docspace.production.documents/6702de67c6ba43a423ca035f/documents/template_680bc498b6890a1324423764/680fbf96e97c7b42ec58f988-1745862550459.jpg",
        };
      },
      onFileClick: async (params, urlObject) => {
        console.log("onFileClick: ", params, urlObject);
      },
      onFileDelete: async (params, urlObject) => {
        console.log("onFileDelete: ", params, urlObject);
      },

      identifier: {
        label: "Identifier",
        options: [
          {
            title: "Plain Identifier Option",
            description: "Identifier details for text",
            value: "customer_text_customidentifierselector",
          },
        ],
      },
      metadata: {
        options: [
          {
            type: 'checkbox',
            label: "Require Photo Uploads",
            description: "Should a photo be required?",
            key: "required",
          },
          {
            type: 'number',
            label: "Quantity",
            description: "How many photos are required?",
            key: "count",
          },
          {
            type: 'divider',
            key: "divider",
          },
          {
            type: 'checkbox',
            label: "Failing Option",
            key: "fail",
          },
        ],
      },
      options: {
        metadata: {
          options: [
            {
              type: 'checkbox',
              label: "Failing Option",
              description: "Trigger deficiency capture.",
              key: "failure",
            },
          ],
        },
      },
      tableColumns: {
        types: [
          'text',
          'dropdown',
          'image',
          'number',
          'multiSelect',
          'date',
          'block',
          'barcode',
          'signature',
        ],
        identifier: {
          label: "Col Identifier",
          options: [
            {
              type: "text",
              title: "Deficiencies",
              description: "Details about identifer for table",
              value: "table_customidentifierselector",
            },
          ],
        },
        metadata: {
          options: [
            {
              type: 'number',
              label: "Require Photo Col",
              description: "Should a photo be required?",
              key: "required",
            },
          ],
        },
        options: {
          metadata: {
            options: [
              {
                type: 'checkbox',
                label: "Failing Option",
                description: "Trigger deficiency capture.",
                key: "failure",
              },
            ],
          },
        },
      },
    },
  };

  const handleChange = (changelogs, updatedDoc) => {
    console.log("Document changed:", changelogs);
    setDocument(updatedDoc);
  };

  return (
    <div style={{ padding: "20px" }}>
      <h1>Complete Field Settings Example</h1>
      <p>
        This example demonstrates the exact fieldSettings from JoyDoc.stories.js
      </p>

      <JoyDoc
        doc={document}
        mode="edit"
        fieldSettings={fieldSettings}
        onChange={handleChange}
      />
    </div>
  );
}

export default CompleteFieldSettingsExample;
```

## Best Practices

### 1. Keep It Simple

Don't overwhelm users with too many custom settings. Focus on what's essential for your use case.

### 2. Use Clear Labels and Descriptions

Help users understand what each setting does with descriptive labels and helpful descriptions.

### 3. Provide Default Values

Set sensible defaults to improve user experience.

### 4. Group Related Settings

Use dividers to organize settings logically.

## Troubleshooting

### Common Issues

**Settings Not Appearing:** Check your target syntax and ensure the field type matches.

**Metadata Not Saving:** Ensure you're using the correct `key` property and that it's unique.

**Settings Hidden When They Should Show:** Check for conflicting `false` values in your settings.

## Summary

Field settings customization in Joyfill allows you to:

* ✅ **Add custom controls** for your specific needs
* ✅ **Hide unnecessary options** to simplify the interface
* ✅ **Target specific field types** with specialized settings
* ✅ **Collect metadata** for your business processes
* ✅ **Create a tailored experience** for your users

The key is to understand your users' needs and create settings that help them build forms more efficiently while collecting the data you need for your application.

For more advanced customization options, refer to the [official Joyfill documentation](https://docs.joyfill.io/docs/customize-settings#/).