> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Function Reference

## Article: Function Reference

## Article Link: https://dev.wix.com/docs/site-extensions/function-libraries/function-reference.md

## Article Content:

# Function Reference

The `functions` section of a function library manifest defines the functions the library exposes. It's a map where each key is a function name and each value describes that function's parameters, return type, and execution characteristics.

## Example

The following example declares a function that capitalizes text:

```ts
functions: {
  capitalize: {
    parameters: [
      { dataType: "text", displayName: "Text to capitalize" },
    ],
    returns: { dataType: "text" },
    async: false,
  },
}
```

## Function fields

A function has the following fields:

| Field | Required | Description |
| --- | --- | --- |
| `parameters` | No | Array of [parameter definitions](#parameter-fields). Maximum 10. Defaults to no parameters. |
| `returns` | No | [Return type definition](#return-type-fields). Defaults to [void](#void-functions). |
| `async` | No | Whether the function returns a Promise. Defaults to `false`. |
| `displayName` | No | Name of the function shown in the editor. |
| `description` | No | Function description. |

## Parameter fields

Each entry in `parameters` describes one argument the function accepts:

| Field | Required | Description |
| --- | --- | --- |
| `dataType` | Yes | The [type of value](https://dev.wix.com/docs/site-extensions/editor-react-components/editor-react-types/overview/about-editor-react-types.md) the parameter accepts. |
| `displayName` | No | Name of the parameter shown in the editor. |
| `description` | No | Parameter description. |
| `optional` | No | Whether the [parameter is optional](#optional-parameters). Only trailing parameters can be optional because JavaScript arguments are positional. Defaults to `false`. |
| `defaultValue` | No | Default the editor shows as a hint. Not passed at runtime, so your implementation must handle the missing value. Used only when `optional` is `true`. |
| `arrayItems` | When `dataType` is `arrayItems` | Defines what elements in the [array](#arrays) look like. |
| `data` | When `dataType` is `data` | Defines the fields inside the [nested object](#nested-objects). |
| `function` | When `dataType` is `function` | Defines the parameters and return type of a [callback parameter](#callback-parameters). |
| `textEnum` | When `dataType` is `textEnum` | List of allowed [string options](#text-enums). |
| `link` | When `dataType` is `link` | Configuration for the [link parameter](#link-parameters), such as supported link types. |

### Optional parameters

Set `optional` to `true` to make a parameter optional. Only trailing parameters can be optional because JavaScript arguments are positional. Use `defaultValue` to give the editor a hint to display for the missing value.

The following example declares `roundNumber` with an optional parameter and a default value:

```ts
functions: {
  roundNumber: {
    parameters: [
      { dataType: "number", displayName: "Value" },
      { dataType: "number", displayName: "Decimal Places", optional: true, defaultValue: 0 },
    ],
    returns: { dataType: "number" },
  },
}
```

### Arrays

For array parameters, set `dataType` to `'arrayItems'`. Then define the array elements under `arrayItems.item`.

```ts
functions: {
  sum: {
    parameters: [
      {
        dataType: "arrayItems",
        displayName: "Numbers to sum",
        arrayItems: {
          item: { dataType: "number" },
        },
      },
    ],
    returns: { dataType: "number" },
  },
}
```

### Nested objects

For complex object parameters, set `dataType` to `'data'`. Then define each field of the object under `data.items`.

```ts
functions: {
  formatUser: {
    parameters: [
      {
        dataType: "data",
        displayName: "User data",
        data: {
          items: {
            firstName: { dataType: "text", displayName: "First Name" },
            lastName: { dataType: "text", displayName: "Last Name" },
          },
        },
      },
    ],
    returns: { dataType: "text" },
  },
}
```

### Text enums

For a fixed set of string options, set `dataType` to `'textEnum'` and list the choices under `textEnum.options`.

```ts
functions: {
  getNextStatus: {
    parameters: [
      {
        dataType: "textEnum",
        displayName: "Current Status",
        textEnum: {
          options: [
            { value: "pending", displayName: "Pending" },
            { value: "processing", displayName: "Processing" },
          ],
        },
      },
    ],
    returns: { dataType: "textEnum" },
  },
}
```

### Callback parameters

A parameter can itself be a function. Set its `dataType` to `'function'`, then describe the callback's parameters and return type under `function`.

```ts
functions: {
  retryOperation: {
    parameters: [
      {
        dataType: "function",
        displayName: "Task to run",
        function: {
          parameters: [
            { dataType: "number", displayName: "Attempt Number" },
          ],
          returns: { dataType: "booleanValue" },
        },
      },
    ],
    returns: { dataType: "booleanValue" },
  },
}
```

### Link parameters

For a parameter that accepts a navigation link, set `dataType` to `'link'`. The optional `link` field restricts which kinds of links are allowed. For the available fields, see [Link](https://dev.wix.com/docs/site-extensions/editor-react-components/editor-react-types/reference/link.md).

```ts
functions: {
  navigateTo: {
    parameters: [
      {
        dataType: "link",
        displayName: "Destination",
        link: {
          linkTypes: ["externalLink", "pageLink"],
        },
      },
    ],
  },
}
```

## Return type fields

The `returns` field describes a function's return value:

| Field | Required | Description |
| --- | --- | --- |
| `dataType` | Yes | The [type of value](https://dev.wix.com/docs/site-extensions/editor-react-components/editor-react-types/overview/about-editor-react-types.md) this function returns. |
| `displayName` | No | Name of the return value shown in the editor. |
| `description` | No | Description of the return value. |
| `arrayItems` | When `dataType` is `arrayItems` | Defines what elements in the returned [array](#arrays) look like. |
| `data` | When `dataType` is `data` | Defines the fields inside the returned [nested object](#nested-objects). |
| `function` | When `dataType` is `function` | Defines the parameters and return type of the returned [callback](#callback-parameters). |
| `textEnum` | When `dataType` is `textEnum` | List of allowed [string options](#text-enums). |
| `link` | When `dataType` is `link` | Configuration for the returned [link](#link-parameters), such as supported link types. |

## Void functions

If a function doesn't return a value, omit `returns`.

```ts
functions: {
  logMessage: {
    parameters: [
      { dataType: "text", displayName: "Message to log" },
    ],
  },
}
```

## Async functions

Set `async` to `true` for a function whose implementation returns a Promise. The `returns` field describes the resolved value's type, not the Promise.

```ts
functions: {
  fetchData: {
    parameters: [
      { dataType: "webUrl", displayName: "API URL" },
    ],
    returns: { dataType: "text" },
    async: true,
  },
}
```

## See also

- [About Function Libraries](https://dev.wix.com/docs/site-extensions/function-libraries/about-function-libraries.md)
- [About Function Libraries in Studio Two](https://dev.wix.com/docs/studio-two/code-your-site/code-model/function-libraries/about-function-libraries.md)
- [About the Function Library Manifest](https://dev.wix.com/docs/site-extensions/function-libraries/about-the-function-library-manifest.md)
- [Function Library Resources Reference](https://dev.wix.com/docs/site-extensions/function-libraries/function-library-resources-reference.md)
- [About Editor React Types](https://dev.wix.com/docs/site-extensions/editor-react-components/editor-react-types/overview/about-editor-react-types.md)