---
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.0.0"
related:
    - title: "Data Types"
      url: "https://www.ag-grid.com/studio/javascript/data-types/"
    - title: "Formatting"
      url: "https://www.ag-grid.com/studio/javascript/formatting/"
    - title: "Expressions"
      url: "https://www.ag-grid.com/studio/javascript/expressions/"
    - title: "Calendars"
      url: "https://www.ag-grid.com/studio/javascript/calendars/"
llms: "https://www.ag-grid.com/studio/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/javascript/creating-calculations/) and [Using Data](https://www.ag-grid.com/studio/javascript/using-data/#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 `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/javascript/formatting/)). |

`editable` is available on field definitions, [expression fields](https://www.ag-grid.com/studio/javascript/expressions/), and Measures. Note fields the user creates in the UI are always fully editable.

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/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/examples/creating-editing-fields/editable-fields/typescript/)

## Editing Expressions

The `Expression` input is only shown for Calculated Columns and Measures the user created themselves. 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.

| 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/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.

## 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/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/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`.