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

# String: Generate dispersed file path

> Generates a nested directory path from a string, distributing files across subdirectories to avoid large flat directories.

export const FormField = ({property, label, required = false, diType, uiPatterns, children}) => {
  const patterns = Array.isArray(uiPatterns) ? uiPatterns : uiPatterns ? [uiPatterns] : [];
  return <div style={{
    margin: '1.5rem 0'
  }}>
      <div style={{
    display: 'flex',
    alignItems: 'baseline',
    flexWrap: 'wrap',
    gap: '0.5rem',
    marginBottom: '0.25rem'
  }}>
        <strong>{label}</strong>
        <span style={{
    fontSize: '0.7rem',
    fontWeight: 600,
    textTransform: 'uppercase',
    letterSpacing: '0.04em',
    color: required ? '#6241f5' : '#6b7280'
  }}>
          {required ? 'Required' : 'Optional'}
        </span>
      </div>

      <div>{children}</div>

      {diType || patterns.length > 0 ? <p style={{
    fontSize: '0.85rem',
    color: '#6b7280',
    marginBottom: 0
  }}>
          {diType ? <>
              See the <a href={`/references/${diType}`}>{diType}</a> reference.{' '}
            </> : null}
          {patterns.length > 0 ? <>
              Accepts a <a href={`/documentation/placeholders-and-patterns/patterns#${patterns[0]}`}>pattern</a>.
            </> : null}
        </p> : null}
    </div>;
};

Turns a file name into a nested folder path, so that files are spread across many subfolders instead of piling up in one huge directory. It takes the first few characters of the value, uses them as folder names, and places the original value at the end as the file. This is a common trick for large media libraries: storing thousands of images in a single folder is slow, but spreading them by their leading characters keeps each folder small and quick to browse.

This documentation describes: [Schema](/schemas/mapper/string-dispersion)

## Fields

<FormField property="depth" label="Depth">
  How many folder levels to create from the start of the value. Defaults to `2`. A higher depth spreads files across more nested folders.
</FormField>

<FormField property="breadth" label="Breadth">
  How many characters make up each folder name. Defaults to `1`. For example, a breadth of `2` uses two characters per folder level.
</FormField>

<FormField property="separator" label="Separator">
  The character placed between folder levels. Defaults to `/`, which suits most file paths.
</FormField>

<FormField property="translations" label="Translations">
  Replaces specific characters when building the folder names, for example to avoid placing a dot in a folder name. Each entry maps a character to its replacement. By default a dot (`.`) is replaced with an underscore (`_`). This only affects the generated folder names; the original value is always kept intact as the final part of the path.
</FormField>

## Sample data

Using the defaults, the first two characters of the file name become two single-character folders, and the original file name is kept at the end.

| Field     | Value |
| --------- | ----- |
| Depth     | `2`   |
| Breadth   | `1`   |
| Separator | `/`   |

Input:

```json theme={null}
{ "filename": "product-image-1234.jpg" }
```

Output:

```json theme={null}
{ "filename": "p/r/product-image-1234.jpg" }
```

With a Depth of `3` and a Breadth of `2`, three folders of two characters each are created from the start of the value.

| Field   | Value |
| ------- | ----- |
| Depth   | `3`   |
| Breadth | `2`   |

Input:

```json theme={null}
{ "filename": "ABCDEFGH.txt" }
```

Output:

```json theme={null}
{ "filename": "AB/CD/EF/ABCDEFGH.txt" }
```

```json Configuration theme={null}
{
  "prototype": "string-dispersion",
  "parameters": {
    "depth": 2,
    "breadth": 1,
    "separator": "/"
  }
}
```