Defining app settings

Apps may configure settings which let users customize the app at the workspace level. Settings live in src/app/settings/ and consist of a schema defined with Settings.defineWorkspaceSchema and a page defined with Settings.defineWorkspacePage, displayed with form components from Settings.useForm. 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)

Only workspace admins can edit workspace settings. However, all workspace members can view the settings.

Example: Basic workspace settings

First, define your settings schema as the default export of src/app/settings/schema.ts:

src/app/settings/schema.ts

import {Settings} from "attio"

export default Settings.defineWorkspaceSchema({
  team_name: Settings.Schema.string(),
  environment: Settings.Schema.string(),
  auto_sync_enabled: Settings.Schema.boolean(),
  sync_interval_minutes: Settings.Schema.number(),
})

Then, define your workspace settings page as the default export of src/app/settings/page.tsx:

src/app/settings/page.tsx

import React from "react"
import {Settings} from "attio/client"

import schema from "./schema"

export default Settings.defineWorkspacePage(schema, () => {
  const {Form, Section, TextInput, Toggle, NumberInput} = Settings.useForm(schema)

  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>
  )
})

The process to create workspace settings is:

Define a schema with Settings.defineWorkspaceSchema at src/app/settings/schema.ts
Define a page with Settings.defineWorkspacePage at src/app/settings/page.tsx
Use Settings.useForm inside the page’s render callback to get form components
Wrap your settings inputs in the <Form/> and organize with <Section/> components

Validation

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

src/app/settings/page.tsx

import React from "react"
import {Settings} from "attio/client"

import schema from "./schema"

export default Settings.defineWorkspacePage(schema, () => {
  const {Form, Section, TextInput, NumberInput} = Settings.useForm(schema)

  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 /> - String input with validation
<NumberInput /> - Numeric input with min/max
<Toggle /> - Boolean toggle switch
<Checkbox /> - Boolean checkbox
<Combobox /> - Dropdown selection
<AttioUserCombobox /> - Select workspace users
<RichTextInput /> - Rich text input

Layout components

<Section /> - Group settings into sections
<InputGroup /> - Group inputs horizontally

Utility components

<Button /> - Action buttons for additional functionality
<WithState /> - Access form state for conditional rendering

Accessing settings in your app

Once your workspace settings are configured, you can access them in different ways. Every setting value is null until it has been set.

With real-time updates

In React components, use the Settings.useSettings hook to get settings that automatically update when changed:

src/app/extensions/team-widget/team-widget-content.tsx

import React from "react"
import {Settings, Widget} from "attio/client"

import schema from "../../settings/schema"

export const TeamWidgetContent = () => {
  const settings = Settings.useSettings(schema)

  // 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 Settings.getSettings and Settings.setSettings to read and write settings. They’re available from both attio/client (for use in extensions, dialogs, etc.) and attio/server (for use in server functions, webhook handlers, and event handlers): In client code:

src/app/extensions/sync-record/extension.tsx

import {Extensions, Settings} from "attio/client"

import schema from "../../settings/schema"

export default Extensions.defineExtension({
  type: "record-action",
  id: "sync-record",
  label: "Sync Record",
  icon: "ArrowsRefresh",
  onTrigger: async ({recordId}) => {
    // Get all settings
    const settings = await Settings.getSettings(schema)

    // Or get a single setting
    const syncEnabled = await Settings.getSettings(schema, "auto_sync_enabled")

    // Update a setting
    await Settings.setSettings(schema, "auto_sync_enabled", true)
  },
})

In server functions:

src/sync-data.server.ts

import {Settings} from "attio/server"

import schema from "./app/settings/schema"

export default async function syncData() {
  // Get all settings
  const settings = await Settings.getSettings(schema)

  // Or get a single setting
  const syncEnabled = await Settings.getSettings(schema, "auto_sync_enabled")

  // Update a setting
  await Settings.setSettings(schema, "auto_sync_enabled", true)

  return {success: true}
}

Workspace settings overview
Settings.defineWorkspaceSchema() - Define the structure and types of your settings
Settings.defineWorkspacePage() - Define the settings page
Settings.useForm() - Build the settings form
Settings.useSettings() - Hook for accessing settings in React components
Settings.getSettings() - Get settings in client or server code
Settings.setSettings() - Set a setting in client or server code
Settings Components

Introduction

Guides

Extensions

Workflow blocks

Notifications

Dialogs

Components

Forms

Icons

Settings

GraphQL

Data fetching

Server

System

Legacy

Defining app settings

Example: Basic workspace settings

Validation

Available components

Input components

Layout components

Utility components

Accessing settings in your app

With real-time updates

Programmatically

​Example: Basic workspace settings

​Validation

​Available components

​Input components

​Layout components

​Utility components

​Accessing settings in your app

​With real-time updates

​Programmatically

​Related documentation

Example: Basic workspace settings

Validation

Available components

Input components

Layout components

Utility components

Accessing settings in your app

With real-time updates

Programmatically

Related documentation