---
product: "AG Studio"
title: "Editable Fields"
description: "The editable property on a field definition controls which of its properties a user may change. Fields a user creates themselves are always fully editable."
framework: javascript
version: "3.1.1"
related:
    - title: "Data Types"
      url: "https://www.ag-grid.com/studio/archive/3.1.1/javascript/data-types/"
    - title: "Formatting"
      url: "https://www.ag-grid.com/studio/archive/3.1.1/javascript/formatting/"
    - title: "Expressions"
      url: "https://www.ag-grid.com/studio/archive/3.1.1/javascript/expressions/"
    - title: "Calendars"
      url: "https://www.ag-grid.com/studio/archive/3.1.1/javascript/calendars/"
llms: "https://www.ag-grid.com/studio/archive/3.1.1/llms.txt"
---

# Editable Fields

The `editable` property on a field definition controls which of its properties a user may change. Fields a user creates themselves are always fully editable.

For the end-user view of this, see [Calculations](https://www.ag-grid.com/studio/archive/3.1.1/analysts/calculations/) and [Fields in Widgets](https://www.ag-grid.com/studio/archive/3.1.1/analysts/fields-in-widgets/#editing-fields) in the User Guide.

## Editing Fields

Fields are fully editable by default. Use the `editable` property on a field definition to lock a field down or to restrict which properties the user can change:

```ts
const fields: AgFieldDefinition[] = [
    { id: 'country', format: 'textFormat' },
    { id: 'sport', format: 'textFormat', editable: false },
    { id: 'gold', format: 'integerFormat', editable: ['name', 'formatOptions'] },
    { id: 'silver', format: 'integerFormat', editable: ['name'] },
];
```

Pass `true` (the default) to make every property editable, `false` to make the field read-only, or an array of `AgFieldEditableKey` values to allow a subset:

| Key | What the user can edit |
| --- | --- |
| `name` | The display name shown wherever the field appears. |
| `description` | The description shown in the Field Panel. |
| `formatOptions` | Formatting options for the field's format type (see [Formatting](https://www.ag-grid.com/studio/archive/3.1.1/javascript/formatting/)). |

These three keys are the full set. `editable` is available on field definitions, [Expressions](https://www.ag-grid.com/studio/archive/3.1.1/javascript/expressions/), and Measures. Fields the user creates in the UI are always fully editable.

`formatOptions` has no effect on a field with no format, or on a field that uses a custom format you registered yourself. The Field Panel shows format options only for the built-in formats (see [Formatting](https://www.ag-grid.com/studio/archive/3.1.1/javascript/formatting/)).

In the example below, select any field in the Data Panel to switch the Edit Panel to its field view. Each field is configured differently:

- **Country**: fully editable (default).
- **Sport**: read-only (`editable: false`).
- **Gold**: name and format options editable (`editable: ['name', 'formatOptions']`).
- **Silver**: name only (`editable: ['name']`).
- **Bronze**: read-only (`editable: false`).

#### Editable Fields

```ts
import {
  AgFieldDefinition,
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const fields: AgFieldDefinition[] = [
  {
    id: "country",
    format: "textFormat",
  },
  {
    id: "sport",
    format: "textFormat",
    editable: false,
  },
  {
    id: "gold",
    format: "integerFormat",
    editable: ["name", "formatOptions"],
  },
  {
    id: "silver",
    format: "integerFormat",
    editable: ["name"],
  },
  {
    id: "bronze",
    format: "integerFormat",
    editable: false,
  },
];

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "1": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "medals.country" },
              { id: "medals.sport" },
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
            ],
          },
        },
      },
      widgetLayout: {
        "1": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 16 },
      },
    },
  ],
  selectedPageId: "a",
  panels: {
    filters: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
};

let studioApi: AgStudioApi;

const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/archive/3.1.1/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", name: "Medals", data, fields }],
    }),
  );
```

[Live example: Editable Fields](https://www.ag-grid.com/studio/archive/3.1.1/examples/creating-editing-fields/editable-fields/typescript/)

### Saved Edits and Locked Properties

A user's edits are saved in the report state (see [Schema State](https://www.ag-grid.com/studio/archive/3.1.1/javascript/creating-editing-fields/#schema-state)). If you later remove a property from `editable`, or set `editable: false`, a saved edit to that property is ignored and the field shows your value again. The saved edit is not deleted, so it applies again if you make the property editable later.

The saved edit is discarded if the user then saves a change to another property of the same field while the property is locked.

## Editing Expressions

Only Calculated Columns and Measures the user created themselves have an `Expression` input. A user can never edit the expression of a Calculated Column or Measure you define, whatever `editable` is set to. A source column has no expression.

### User-Created Expressions

A user can edit the name, description, expression and format of a Calculated Column or Measure they created.

The expression syntax is case-insensitive throughout: function names, booleans, and the table and field names in a reference all match regardless of case. The input offers autocomplete for functions and fields, bracket matching, and inline syntax errors. An invalid expression is still saved, but the field produces no values until it parses. A new field with no expression yet also produces no values, so a widget shows it as an empty column.

| Description | Syntax |
| --- | --- |
| Field references | `Medals[Gold]`, `[Total Medals]`, `'Completed Orders'[Date]` |
| Strings | `"string"` (double quotes only) |
| Numbers | `123`, `1.23`, `1e3` |
| Booleans | `TRUE`, `FALSE` |
| Arithmetic operators | `+`, `-`, `*`, `/`, `^` |
| Brackets | `3 * (2 + 1)` |
| Comparison operators | `>`, `>=`, `<`, `<=`, `=`, `==` (alias for `=`), `<>` (not equal) |
| Boolean operators | `NOT x`, `&&`, `\|\|` |
| String concatenation | `a & b` |
| Function calls | `ADD(a, b)` |
| Comments | `-- Single Line`, `// Single Line`, `/* Multi Line */` |

For a list of functions, see [Function Expressions](https://www.ag-grid.com/studio/archive/3.1.1/javascript/expressions/#function-expression-operators).

> **Note**
>
> The Format input should be set to a value that relates the expression. For example, if the expression returns a number, the Format could be set to Integer or Decimal, but not Text. Widgets using fields with such mismatches may fail to display data.

In the example below, the `Total Medals` Calculated Column is set in `initialState.schema`, as if the user had created it. Select it in the Data Panel and click Edit to change its expression.

#### User-Created Expressions

```ts
import {
  AgFieldDefinition,
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const fields: AgFieldDefinition[] = [
  { id: "country", format: "textFormat" },
  { id: "gold", format: "integerFormat" },
  { id: "silver", format: "integerFormat" },
  { id: "bronze", format: "integerFormat" },
];

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "1": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "medals.country" },
              { id: "expression-1", aggregation: "sum" },
            ],
          },
        },
      },
      widgetLayout: {
        "1": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 16 },
      },
    },
  ],
  selectedPageId: "a",
  panels: {
    filters: {
      collapsed: true,
    },
  },
  schema: {
    fields: {
      "expression-1": {
        name: "Total Medals",
        expression: "[medals.gold] + [medals.silver] + [medals.bronze]",
      },
    },
    expressions: [
      {
        id: "expression-1",
        tableId: "medals",
        isMeasure: false,
        format: "integerFormat",
      },
    ],
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
};

let studioApi: AgStudioApi;

const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/archive/3.1.1/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", name: "Medals", data, fields }],
    }),
  );
```

[Live example: User-Created Expressions](https://www.ag-grid.com/studio/archive/3.1.1/examples/creating-editing-fields/user-expressions/typescript/)

### Developer-Defined Expressions

For a Calculated Column or Measure you define, `editable` controls only the name, description and format options. The user cannot change the expression, and no setting changes this.

The Field Panel shows a string expression read-only. It does not show an expression defined as an `AgExpression` object. To let users see an expression, define it as a string:

```ts
const expressions: AgExpressionFieldDefinition[] = [
    // Not shown in the Field Panel
    {
        id: 'goldAndSilverObject',
        name: 'Gold and Silver (Object)',
        isMeasure: false,
        expression: {
            operator: 'add',
            inputs: [{ id: 'medals.gold' }, { id: 'medals.silver' }],
        },
    },
    // Shown read-only in the Field Panel
    {
        id: 'goldAndSilverString',
        name: 'Gold and Silver (String)',
        isMeasure: false,
        expression: '[medals.gold] + [medals.silver]',
    },
];
```

A string expression refers to fields by their IDs, as in the [Schema State](https://www.ag-grid.com/studio/archive/3.1.1/javascript/creating-editing-fields/#schema-state) below. Both definitions produce the same values.

In the example below, both Calculated Columns use `editable: ['name', 'formatOptions']`. Select each one in the Data Panel: only the string expression is shown. Click Edit: the name can be changed, but neither field has an `Expression` input.

#### Developer-Defined Expressions

```ts
import {
  AgExpressionFieldDefinition,
  AgFieldDefinition,
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const fields: AgFieldDefinition[] = [
  { id: "country", format: "textFormat" },
  { id: "gold", format: "integerFormat" },
  { id: "silver", format: "integerFormat" },
];

const expressions: AgExpressionFieldDefinition[] = [
  {
    id: "goldAndSilverString",
    name: "Gold and Silver (String)",
    isMeasure: false,
    format: "integerFormat",
    expression: "[medals.gold] + [medals.silver]",
    editable: ["name", "formatOptions"],
  },
  {
    id: "goldAndSilverObject",
    name: "Gold and Silver (Object)",
    isMeasure: false,
    format: "integerFormat",
    expression: {
      operator: "add",
      inputs: [{ id: "medals.gold" }, { id: "medals.silver" }],
    },
    editable: ["name", "formatOptions"],
  },
];

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "1": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "medals.country" },
              { id: "goldAndSilverString", aggregation: "sum" },
              { id: "goldAndSilverObject", aggregation: "sum" },
            ],
          },
        },
      },
      widgetLayout: {
        "1": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 16 },
      },
    },
  ],
  selectedPageId: "a",
  panels: {
    filters: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
};

let studioApi: AgStudioApi;

const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/archive/3.1.1/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", name: "Medals", data, fields }],
      expressions,
    }),
  );
```

[Live example: Developer-Defined Expressions](https://www.ag-grid.com/studio/archive/3.1.1/examples/creating-editing-fields/developer-expressions/typescript/)

> **Note**
>
> Users can never edit an expression you define, and the Field Panel does not show an expression defined as an `AgExpression` object. Define the expression as a string if users need to see it.

## Schema State

User edits and user-created fields are both persisted in the `schema` slice of the report state, as an `AgSchemaState`. Save and restore it with the rest of your report state - see [State](https://www.ag-grid.com/studio/archive/3.1.1/javascript/state/) for the full state model.

```js
const schema = {
    fields: {
        'medals.gold': {
            name: 'Golds'
        },
        'expression-1': {
            name: 'Total Medals',
            expression: '[medals.gold] + [medals.silver] + [medals.bronze]',
        },
    },
    expressions: [
        {
            isMeasure: false,
            id: 'expression-1',
            tableId: 'medals',
            format: 'integerFormat'
        }
    ],
};
```

`fields` contains per-field overrides for both developer and user created fields. It is keyed by the ID of each field. Each entry may contain:

- `name`
- `description`
- `format` - a format string (only available for built-in formats, see [Formatting](https://www.ag-grid.com/studio/archive/3.1.1/javascript/formatting/#format-options))
- `expression` - only for user created expressions

> **Note**
>
> Serialised expressions encode field references using their ID rather than their name. E.g. `Medals[Gold]` is serialized as `[medals.gold]`. The user will always see the former.

`expressions` declares the fields the user created. Each entry has:

- `id` (required) - a unique ID (auto-generated when created via the UI)
- `tableId` (required) - the ID of the data source the field was added to.
- `isMeasure` (required) - `true` for a Measure, `false` for a Calculated Column.
- `format` - the format type, defaulting to `integerFormat`.
