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

# Defining app settings

> How to define workspace-level settings for your app

<img className="dark:hidden" width="720" height="440" noZoom src="https://mintcdn.com/attio/jXl5_SFM_Le7vWWN/images/workspace-settings-guide.png?fit=max&auto=format&n=jXl5_SFM_Le7vWWN&q=85&s=b8fc2fa68d49d58f3f737e3cc02e54bc" data-path="images/workspace-settings-guide.png" />

<img className="hidden dark:block" width="720" height="440" noZoom src="https://mintcdn.com/attio/jXl5_SFM_Le7vWWN/images/workspace-settings-guide-dark.png?fit=max&auto=format&n=jXl5_SFM_Le7vWWN&q=85&s=cd34fc601b5bf96df6c367992074683a" data-path="images/workspace-settings-guide-dark.png" />

Apps may configure settings which let users customize the app at the workspace level.

Settings are defined using a [workspace settings schema](../settings/app-settings-schema) at `src/app.settings.ts` and displayed with form components from [`useWorkspaceSettingsForm()`](../settings/use-workspace-settings-form).

Unlike regular forms in dialogs, workspace settings forms automatically save changes and don't require
a submit button or `onSubmit` handler. Each field saves individually:

* Text inputs and number inputs save `onBlur` (when the user leaves the field)
* Toggles, checkboxes, and comboboxes save `onChange` (immediately when changed)

<Note>
  Only workspace admins can edit workspace settings. However, all workspace members can view the
  settings.
</Note>

## Example: Basic workspace settings

First, define your settings schema. This **must** be in a file called `app.settings.ts` at `src/app.settings.ts`:

```typescript app.settings.ts theme={"system"}
import {Settings, type SettingsSchema} from "attio"

const appSettingsSchema = {
  workspace: {
    team_name: Settings.string(),
    environment: Settings.string(),
    auto_sync_enabled: Settings.boolean(),
    sync_interval_minutes: Settings.number(),
  },
} satisfies SettingsSchema

export default appSettingsSchema
```

Then, create your workspace settings page to display these settings in a configurable form:

```tsx workspace-settings.tsx theme={"system"}
import React from "react"
import {useWorkspaceSettingsForm} from "attio/client"
import type {App} from "attio"

export const workspaceSettings: App.Settings.Workspace = {
  Page,
}

function Page() {
  const {Form, Section, TextInput, Toggle, NumberInput} = useWorkspaceSettingsForm()

  return (
    <Form>
      <Section title="General" description="Basic workspace settings.">
        <TextInput label="Team name" name="team_name" minLength={2} maxLength={50} />
        <TextInput label="Environment" name="environment" placeholder="production" />
      </Section>

      <Section title="Sync Settings" description="Control how data syncs.">
        <Toggle
          label="Enable automatic sync"
          name="auto_sync_enabled"
          description="Automatically sync data in the background."
        />
        <NumberInput
          label="Sync interval (minutes)"
          name="sync_interval_minutes"
          min={5}
          max={1440}
          placeholder={60}
        />
      </Section>
    </Form>
  )
}
```

Finally, register it in your `app.ts`:

```typescript app.ts theme={"system"}
import type {App} from "attio"
import {workspaceSettings} from "./workspace-settings"

export const app: App = {
  settings: {
    workspace: workspaceSettings,
  },
  // ... other app configuration
}
```

The process to create workspace settings is:

1. Define a [workspace settings schema](../settings/app-settings-schema) at `src/app.settings.ts`
2. Create a workspace settings object with a `Page`
3. Use [`useWorkspaceSettingsForm()`](../settings/use-workspace-settings-form) to get form components
4. Wrap your settings inputs in the `<Form/>` and organize with `<Section/>` components
5. Register the settings in your `app.ts`

## Validation

Unlike regular forms where validation is defined in the schema, workspace settings validation
is specified directly on the input components:

```tsx workspace-settings-validation.tsx theme={"system"}
function Page() {
  const {Form, Section, TextInput, NumberInput} = useWorkspaceSettingsForm()

  return (
    <Form>
      <Section title="Configuration">
        {/* String validation */}
        <TextInput
          label="Organization name"
          name="organization_name"
          minLength={2}
          maxLength={100}
        />

        {/* URL validation */}
        <TextInput label="Webhook URL" name="webhook_url" type="url" url />

        {/* Multiline text with character limit */}
        <TextInput label="Description" name="description" multiline maxLength={500} />

        {/* Number validation */}
        <NumberInput label="Timeout (seconds)" name="timeout_seconds" min={1} max={300} />
      </Section>
    </Form>
  )
}
```

## Available components

Workspace settings forms support the following components:

### Input components

* [`<TextInput />`](../components/workspace-settings/text-input) - String input with validation
* [`<NumberInput />`](../components/workspace-settings/number-input) - Numeric input with min/max
* [`<Toggle />`](../components/workspace-settings/toggle) - Boolean toggle switch
* [`<Checkbox />`](../components/workspace-settings/checkbox) - Boolean checkbox
* [`<Combobox />`](../components/workspace-settings/combobox) - Dropdown selection
* [`<AttioUserCombobox />`](../components/workspace-settings/attio-user-combobox) - Select workspace users

### Layout components

* [`<Section />`](../components/workspace-settings/section) - Group settings into sections
* [`<InputGroup />`](../components/workspace-settings/input-group) - Group inputs horizontally

### Utility components

* [`<Button />`](../components/workspace-settings/button) - Action buttons for additional functionality
* [`<WithState />`](../components/workspace-settings/with-state) - Access form state for conditional rendering

## Accessing settings in your app

Once your workspace settings are configured, you can access them in different ways:

### With real-time updates

In React components, use the [`useWorkspaceSettings()`](../settings/use-workspace-settings) hook to get settings that automatically update when changed:

```tsx widget.tsx theme={"system"}
import {useWorkspaceSettings, Widget} from "attio/client"

export const Widget = () => {
  const settings = useWorkspaceSettings()

  // Access your settings with full type safety
  // Automatically re-renders when settings change
  return (
    <Widget.TextWidget>
      <Widget.Text.Primary>Team: {settings.team_name}</Widget.Text.Primary>
    </Widget.TextWidget>
  )
}
```

### Programmatically

Use these functions to get and set settings. They're available from both `attio/client` (for use in React components, actions, etc.) and `attio/server` (for use in server functions):

**In client code:**

```tsx record-action.tsx theme={"system"}
import {getWorkspaceSettings, getWorkspaceSetting, setWorkspaceSetting} from "attio/client"
import type {App} from "attio"

export const syncAction: App.Record.Action = {
  id: "sync-record",
  label: "Sync Record",
  icon: "Refresh",
  onTrigger: async ({recordId}) => {
    // Get all settings
    const settings = await getWorkspaceSettings()

    // Or get a single setting
    const syncEnabled = await getWorkspaceSetting("auto_sync_enabled")

    // Update a setting
    await setWorkspaceSetting("auto_sync_enabled", true)
  },
}
```

**In server functions:**

```tsx sync-data.server.ts theme={"system"}
import {getWorkspaceSettings, getWorkspaceSetting, setWorkspaceSetting} from "attio/server"

export default async function syncData() {
  // Get all settings
  const settings = await getWorkspaceSettings()

  // Or get a single setting
  const syncEnabled = await getWorkspaceSetting("auto_sync_enabled")

  // Update a setting
  await setWorkspaceSetting("auto_sync_enabled", true)

  return {success: true}
}
```

See the documentation for [`getWorkspaceSettings()`](../settings/get-workspace-settings), [`getWorkspaceSetting()`](../settings/get-workspace-setting), and [`setWorkspaceSetting()`](../settings/set-workspace-setting) for more details.

## Related documentation

* [Workspace Settings Entry Point](../entry-points/workspace-settings)
* [`useWorkspaceSettings()`](../settings/use-workspace-settings) - Hook for accessing settings in React components
* [`getWorkspaceSettings()`](../settings/get-workspace-settings) - Get all settings in server actions
* [`getWorkspaceSetting()`](../settings/get-workspace-setting) - Get a single setting in server actions
* [`setWorkspaceSetting()`](../settings/set-workspace-setting) - Set a single setting in server actions
* [`useWorkspaceSettingsForm()`](../settings/use-workspace-settings-form) - Hook for creating the settings form
* [Workspace Settings Schema](../settings/app-settings-schema)
* [Settings Components](../components/workspace-settings/form)