Skip to main content
The workspace settings schema defines the structure and types of the settings that users can configure for your app. This schema is used by useWorkspaceSettingsForm() to provide type-safe form components, ensuring that each component (like TextInput, NumberInput, or Toggle) can only reference fields with matching types in the schema (e.g., TextInput can only reference Settings.string() fields).

​
File Location

The settings schema must be defined in a file at src/app.settings.ts. This file location is required and cannot be changed.

​
Structure

app.settings.ts
import {Settings, type SettingsSchema} from "attio"

const appSettingsSchema = {
  workspace: {
    // Your workspace settings go here
  },
} satisfies SettingsSchema

export default appSettingsSchema
All settings are workspace-level, meaning they apply to the entire workspace where your app is installed.

​
Available Setting Types

The Settings object provides the following types:

​
Settings.string()

Defines a string setting. Use this for text values like names, URLs, or identifiers. 
workspace: {
  display_name: Settings.string(),
  webhook_url: Settings.string(),
  environment: Settings.string(),
}

​
Settings.boolean()

Defines a boolean setting. Use this for toggles, checkboxes, or on/off configurations. 
workspace: {
  auto_sync_enabled: Settings.boolean(),
  notifications_enabled: Settings.boolean(),
}

​
Settings.number()

Defines a numeric setting. Use this for counts, durations, or other numerical values. 
workspace: {
  sync_interval_minutes: Settings.number(),
  max_records_per_sync: Settings.number(),
  timeout_seconds: Settings.number(),
}

​
Complete Example

app.settings.ts
import {Settings, type SettingsSchema} from "attio"

const appSettingsSchema = {
  workspace: {
    display_name: Settings.string(),
    environment: Settings.string(),
    auto_sync_enabled: Settings.boolean(),
    sync_interval_minutes: Settings.number(),
    max_records_per_sync: Settings.number(),
    webhook_url: Settings.string(),
    notifications_enabled: Settings.boolean(),
    email_notifications: Settings.boolean(),
    default_assignee_id: Settings.string(),
    timeout_seconds: Settings.number(),
  },
} satisfies SettingsSchema

export default appSettingsSchema

​
Using the Schema

Once you’ve defined your schema, you can use it in your workspace settings form:
workspace-settings.tsx
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, TextInput, Toggle, NumberInput, Section} = useWorkspaceSettingsForm()

  return (
    <Form>
      <Section title="General Settings">
        <TextInput label="Display name" name="display_name" />
        <TextInput label="Environment" name="environment" />
      </Section>

      <Section title="Sync Configuration">
        <Toggle label="Enable automatic sync" name="auto_sync_enabled" />
        <NumberInput label="Sync interval (minutes)" name="sync_interval_minutes" />
        <NumberInput label="Max records per sync" name="max_records_per_sync" />
      </Section>

      <Section title="Webhook Settings">
        <TextInput label="Webhook URL" name="webhook_url" type="url" />
      </Section>
    </Form>
  )
}