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

# User settings

> How to update user settings in Atoti UI via Atoti Admin UI or the Settings popup, including managing organization-wide defaults, consuming settings via the useSetting hook, registering custom SettingDefinition objects, and grouping them with SettingsGroup.

Settings can be used to customize the user experience. They can be edited in **Atoti Admin UI**. Unlike for [permissions](./permissions), individual users can edit their own settings from the UI using [the **Settings** popup](../../user-guide/navigate-atoti-ui/settings). See [CoreSettings](../reference/types#coresettings) for the full list of available settings.

## Update a user's settings

To change the settings of an individual user, follow these steps:

* Open **Atoti Admin UI**. If you do not know how to, please contact the support.
* Open the file named *settings* in the folder `ui/users/<username>` or create it if it does not exist.
  * To create it, right click the folder in the tree and click *Create File*.
* Edit it and press Ctrl/Cmd + S to save. The format of this file is JSON. Below is an example:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "homePageLayout": "list",
  "dataModel.isSimplified": true
}
```

* Ask the user to refresh.

<Note>
  The user needs to have access to this file. To make sure they do, right-click the file in the tree and click "properties". A popup will open. The name of the user must be in *Owners* and *Readers*.

  <Frame>
    <img src="https://mintcdn.com/activeviam/6mkB_0OOZ4thIY0X/data-visualization/atoti-ui/5.2/static/img/settings/properties.png?fit=max&auto=format&n=6mkB_0OOZ4thIY0X&q=85&s=014d80f18c04f9e79d24f141243ce669" alt="File properties popup in Atoti Admin UI showing Owners and Readers fields" width="1379" height="580" data-path="data-visualization/atoti-ui/5.2/static/img/settings/properties.png" />
  </Frame>
</Note>

## Update all users' settings

Default settings can be created for all users in your organization at once. To do it, edit the file named *organization\_settings* in the folder `ui`. This file shares the same format as individual user settings files (see above). Note that to be taken into account, it must have `ROLE_USER` in its readers.

## Consume settings

The [useSetting](../reference/hooks#usesetting) hook allows to consume the value of a setting in a React component. For instance, here is how to consume the value of the `table.defaultSize` setting:

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
import { useSetting } from "@activeviam/atoti-ui-sdk";

const MyComponent = () => {
  const [tableSize] = useSetting("table.defaultSize");
};
```

Note that the hook also returns a function to update the value of this setting, and whether the setting is currently being loaded from the server. If necessary, you can access these as follows:

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
const [tableSize, updateTableSize, { isLoading }] =
  useSetting("table.defaultSize");
```

## Extend settings

Atoti UI extensions can register their own settings to customize the user experience. To add a custom setting, first you must create a [setting definition](../reference/types#settingdefinition). For instance:

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
import { SettingDefinition } from "@activeviam/atoti-ui-sdk";

const mySelectSetting: SettingDefinition<"my.feature.option"> = {
  key: "my.feature.option",
  type: "select",
  defaultValue: "one",
  options: ["one", "two", "three"],
  mode: "single",
  translations: {
    "en-US": {
      description: "The chosen option for my feature",
      title: "My option",
    },
  },
};

const myInputSetting: SettingDefinition<"my.feature.text"> = {
  key: "my.feature.text",
  type: "input",
  defaultValue: "hello world!",
  translations: {
    "en-US": {
      description: "The text setting for my feature",
      title: "My text",
    },
  },
};

const mySettings = [mySelectSetting, myInputSetting];
```

<Note>
  Users can search for settings by their titles, but you can also add search tokens for your settings if you want them to be matched by more search inputs:

  ```diff theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
  const myInputSetting: SettingDefinition<"my.feature.text"> = {
  + searchTokens: ["hello", "world"],
  };
  ```
</Note>

Then register these setting definitions in your extension's `activate` function:

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
import { ExtensionModule } from "@activeviam/atoti-ui-sdk";

const extension: ExtensionModule = {
  activate: async (configuration) => {
    configuration.settings.push(...mySettings);
  },
};
```

This makes your settings accessible to your users and editable in [the **Settings** popup](../../user-guide/navigate-atoti-ui/settings). And you can consume them via the `useSetting` hook as described [above](#consume-settings).

<Warning>
  If you are using TypeScript, calling `useSetting` as shown above will throw an
  error. The section below shows how to fix it.
</Warning>

### Typing

In order to avoid the error thrown by TypeScript when calling `useSetting` to retrieve the value of an extension setting, we need to create the TypeScript type representing the settings of our application (including the ones registered by our extension). It is done by leveraging the [ExtendedSettings](../reference/types#extendedsettings) type as follows:

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
import { ExtendedSettings } from "@activeviam/atoti-ui-sdk";

export type MySettings = ExtendedSettings<typeof mySettings>;
```

Then we must pass this type when calling `useSetting`:

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
const [myOption] = useSetting<MySettings, "my.feature.option">(
  "my.feature.option",
);
```

This fixes the error and also types our variable `myOption` appropriately.

### Group settings

Settings can be grouped together in a single section within [the **Settings** popup](../../user-guide/navigate-atoti-ui/settings). This is particularly useful in order to group together several settings that are relevant to a single feature. You might have noticed that this is even leveraged for core Atoti UI settings related to table widgets and to smart filtering.

To group settings together, you can create a [SettingsGroup](../reference/types#settingsgroup):

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
import { SettingsGroup } from "@activeviam/atoti-ui-sdk";

const mySettingsGroup: SettingsGroup = {
  key: "my.feature",
  settings: mySettings,
  type: "group",
  translations: {
    "en-US": {
      description: "Settings of my feature",
      title: "My feature",
    },
  },
};
```

<Note>
  You can also make your group act as a setting of its own, using the `hasCheckbox` and `defaultValue` attributes of [SettingsGroup](../reference/types#settingsgroup). This will turn the title of your setting group into a checkbox within the **Settings** popup, allowing users to switch the whole feature on or off easily.

  ```diff theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
  const mySettingsGroup: SettingsGroup = {
  + hasCheckbox: true,
  + defaultValue: true,
  };
  ```
</Note>

<Tip>
  If you group settings together, we recommend that the keys of the settings in
  the group start by the key of the group. This increases clarity and avoids the
  risk that keys of your settings clash with those from a different extension.
  Setting keys must be unique.
</Tip>