---
title: "Studio Overview"
framework: react
version: "2.1.2"
---

# Studio Overview

This section provides key information for configuring and interacting with Studio.

## Studio Properties

Studio is configured via props on the `AgStudio` component. Props consist of simple types, arrays, complex objects and callback functions.

```jsx
<AgStudio
    // Simple attributes
    enableRtl
    // Component state
    data={data}
    // Callback
    getLocaleText={getLocaleText}
    // Event handlers
    onStateUpdated={onStateUpdated}
/>
```

> **Note**
>
> When setting properties, it's best to treat non-simple types as immutable objects (e.g. by using `useState` or `useMemo`). See [React Best Practices](https://www.ag-grid.com/studio/react/react-best-practices/).

### Updating Studio Properties

It is a common requirement to update a Studio property after Studio has been created. For example, you may want to change `mode` via an application toggle.

Simply update your state and studio will respond to the new value. In this example the mode will switch to view.

```jsx
const [mode, setMode] = useState('edit');

// Callback to update the mode
const updateMode = () => setMode('view');

<AgStudio mode={mode} />
```

We recommend updating properties via `AgStudio` props but it is also possible to updated a property via `api.setProperty` or `api.updateProperties`.

```js
// update the mode
api.setProperty('mode', 'view');
```

### Initial Studio Properties

A small number of Studio properties do **not** support updating their value. Their value is only read during the initial setup of Studio. These options are marked as `Initial` on the [Properties Reference](https://www.ag-grid.com/studio/react/studio-properties/). For these properties Studio must be destroyed and re-created for the new value to take effect.

> **Note**
>
> Not all Studio Properties support updates. These are marked as Initial.

For a full list of properties, see [Properties Reference](https://www.ag-grid.com/studio/react/studio-properties/).

## Studio Events

As a user interacts with Studio, events will be fired to enable your application to respond to specific actions.

To listen to an event pass a callback to the `AgStudio` component for the given event. All events start with the prefix `on`, i.e the `stateUpdated` event has the prop name `onStateUpdated`. We recommend the use of `useCallback` to avoid wasted renders: see [React Best Practices](https://www.ag-grid.com/studio/react/react-best-practices/).

```ts
const onStateUpdated = useCallback((params: AgStudioStateUpdatedEvent) => {
  console.log('State was updated')
}, []);

<AgStudio onStateUpdated={onStateUpdated} />
```

> **Note**
>
> TypeScript users can take advantage of the events' interfaces. Construct the interface name by prefixing the event name with `AgStudio` and suffixing with `Event`. For example, the `stateUpdated` event uses the interface `AgStudioStateUpdatedEvent`.

For a full list of events, see [Studio Events](https://www.ag-grid.com/studio/react/studio-events/).

## Studio API

The API of Studio can be accessed via a ref passed to the `AgStudio` component.

```jsx
// Create a studioRef
const studioRef = useRef();

const onClick = useCallback(() => {
    // Use the studioRef to access the API
    studioRef.current?.api.getState();
}, []);

<AgStudio ref={studioRef}  />
```

> **Note**
>
> The `studioRef.current` value will not be defined until after the AgStudio component has been initialised. If you want to access the API as soon as it's available (e.g. do initialisation work), consider listening to the `apiReady` event.

The `api` is also provided on the params for all Studio events and callbacks.

```jsx
// access API directly within event handler
onApiReady = useCallback((event: AgStudioApiReadyEvent) => {
    event.api.getState();
},[]);

<AgStudio onApiReady={onApiReady} />
```

For a full list of API methods, see [Studio API](https://www.ag-grid.com/studio/react/studio-api/).

## Studio State

As a user interacts with Studio they may change state such as widget layout, formatting, filtering, etc. This state is independent of the configuration, and to provide save and restore capabilities Studio enables applications to save / restore this state.

For a full list of the state properties, see [Studio State](https://www.ag-grid.com/studio/react/state/).

## Studio Lifecycle

An application may need to perform actions when Studio is first initialised, or about to be destroyed.

For full details about how to interact with Studio at these key moments see: [Studio Lifecycle](https://www.ag-grid.com/studio/react/studio-lifecycle/).

## Studio Errors

When errors occur in state or data validation, an error event will be emitted.

```jsx
const onErrorRaised = (params) => {
    // handle error (e.g. prompt user to load a different report)
};

<AgStudio onErrorRaised={onErrorRaised} />
```

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `errorRaised` | `AgStudioErrorRaisedEvent` |  | An error has occurred within Studio. |