# Settings

Source: https://developers.swell.is/apps/settings

App settings are a means of providing a standardized model and UI for a merchant to configure an application’s behavior. When installed, a merchant can access your app-specific settings page within the Swell dashboard. Setting values managed by the merchant are then made available to the application in configurations and via API.

### Configurable interface

As a developer, you can configure settings using the same syntax as with Content fields. This approach allows you to fine-tune your app settings interface for various use cases, while offering an easy-to-use interface for merchants.

### Defaults and upgrades

It’s possible to iterate on your application’s settings over time by introducing new fields and behavior. New setting fields are automatically added to an existing user’s schema as they upgrade their version of your app in the dashboard.

### Actions

A settings file's `actions` add items to the Actions menu on the app's page in the dashboard, and a field with `type: "action"` adds a button among the settings fields. Both run an app function or workflow when clicked, and are disabled while the settings have unsaved changes. See [Actions](https://developers.swell.is/apps/actions).

## Reference

| Property | Description |
| --- | --- |
| label | Section label displayed in the Swell dashboard. |
| description | Description of the settings, displayed in the Swell dashboard. |
| fields | Array of content fields to configure the setting inputs and the underlying data model. |
| actions | Actions listed in the Actions menu on the app's page in the Swell dashboard. See Actions. |

Settings use the same schema as do content `fields` to configure the app's settings UI in the Swell dashboard, offering a simple way to create a rich user experience for merchants.

→ See the [content model](https://developers.swell.is/backend-api/content-models/the-content-model) fields object for more details.

## Examples

App settings are standardized way to present options for merchants to configure your application. Using the same field types as with content models, you can easily define a schema for your code to leverage and a user interface for merchants.

Here’s an example setting configuration for a product ranking system:

**settings/ranking.json**

```json
{
	"label": "Rankings",
	"description": "Manage settings that determine how rankings are calculated",
	"fields": [
		{
			"id": "update_product_rank",
			"type": "toggle",
			"label": "Automatically update product rankings",
			"default": false
		},
		{
			"id": "update_interval",
			"condition": "can_capture_metrics",
			"type": "radio",
			"label": "Update frequency",
			"options": [
				{ "value": "continuously", "label": "Continuously" },
				{ "value": "daily", "label": "Daily" }
			]
			"default": "continuously"
		}
	]
}
```

In this example, we introduce a toggle (boolean) setting `update_product_rank` that can be edited by a merchant in the admin dashboard. Note if your app has multiple setting configurations, they will be displayed in a grouped interface in the dashboard.

Your app can retrieve these settings on the fly to adapt your logic accordingly. Here’s an example of how to retrieve settings from within an app function:

**Retrieving app settings**

```javascript
const settings = await req.swell.settings()
```

Another common approach is to act upon settings from an App function. Here’s an example that shows how to use settings to limit invocation of a function:

**functions/update-product-rank.ts**

```typescript
import { updateProductRank, updateProductRankDaily } from './lib/products';

export const config: SwellConfig = {
	description: 'Update product rankings',
	model: {
    collection: 'products',
		events: ['updated'],
		conditions: {
			$settings: {
				ranking: { update_product_rank: true },
			},
		},
	},
};

export default function (req: SwellRequest) {
	const { ranking: { update_interval } } = await req.swell.settings();

	if (update_interval === 'continuously') {
		await updateProductRank(req.data);
	} else if (update_interval === 'daily') {
		await updateProductRankDaily();
	}
}
```

In this example, we use the `$settings` property as a condition to match only when the `update_product_rank` setting is enabled.

### Updating settings schemas

During the lifecycle of an application, it is often necessary to add or deprecate settings. When your App is updated with new settings, the platform will automatically append those to the merchant’s existing configuration, maintaining existing setting values while adding new ones.

This approach allows developers to add new functionality over time without affecting the integrity of existing user data.