Defining app settings

How to define workspace-level settings for your app

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:

1. Define a schema with Settings.defineWorkspaceSchema at src/app/settings/schema.ts
2. Define a page with Settings.defineWorkspacePage at src/app/settings/page.tsx
3. Use Settings.useForm inside the page’s render callback to get form components
4. 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

Settings.useForm returns the form and the components that go in it:

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
• <RadioGroup /> - Single choice from a list
• <RichTextInput /> - Rich text input

Layout components

• <Section /> - Group settings into sections
• <InputGroup /> - Group inputs horizontally
• <Fieldset /> - Group a radio group or checkboxes under a legend

Utility components

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

Other components

Other attio/client components can sit next to the settings inputs, inside a Section. A few aren’t supported on settings pages; see supported components.

src/app/settings/page.tsx

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

import schema from "./schema"
import {useRecentSyncs} from "./use-recent-syncs"

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

  return (
    <Form>
      <Section title="Sync Settings">
        <Toggle label="Enable automatic sync" name="auto_sync_enabled" />
        <Table label="Recent syncs">
          <Table.Header>
            <Table.HeaderCell>Started</Table.HeaderCell>
            <Table.HeaderCell>Status</Table.HeaderCell>
          </Table.Header>
          <Table.Body>
            {syncs.map((sync) => (
              <Table.Row key={sync.id}>
                <Table.Cell>{sync.startedAt}</Table.Cell>
                <Table.Cell>
                  <Table.Cell.Badge color={sync.succeeded ? "green" : "red"}>
                    {sync.succeeded ? "Succeeded" : "Failed"}
                  </Table.Cell.Badge>
                </Table.Cell>
              </Table.Row>
            ))}
          </Table.Body>
        </Table>
      </Section>
    </Form>
  )
})

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

Related documentation

• 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