Workspace settings

Workspace settings allow users to configure your app at the workspace level. Settings are displayed in the app’s details page and are automatically saved when users make changes.

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

Settings live in src/app/settings/ and consist of two files:

schema.ts default-exports a Settings.defineWorkspaceSchema call declaring the setting fields and their types.
page.tsx default-exports a Settings.defineWorkspacePage call rendering the settings form.

Example

First, define your settings schema:

src/app/settings/schema.ts

import {Settings} from "attio"

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

Then define the settings page. Call Settings.useForm with the schema to get form components pre-typed against it:

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">
        <TextInput label="Team name" name="team_name" />
      </Section>

      <Section title="Sync Settings">
        <Toggle label="Enable automatic sync" name="auto_sync_enabled" />
        <NumberInput
          label="Sync interval (minutes)"
          name="sync_interval_minutes"
          min={5}
          max={1440}
        />
      </Section>
    </Form>
  )
})

Reading and writing settings

Every setting value is null until it has been set. Beyond the settings page itself, your app can access settings anywhere:

Settings.useSettings(schema) - read settings reactively in React components.
Settings.getSettings(schema, key?) - read settings from client or server code.
Settings.setSettings(schema, key, value) - write a setting from client or server code.

Type safety

The schema provides type safety between your settings definitions and form components. For example:

TextInput, AttioUserCombobox, and Combobox can only reference fields defined as Settings.Schema.string()
NumberInput can only reference fields defined as Settings.Schema.number()
Toggle and Checkbox can only reference fields defined as Settings.Schema.boolean()

TypeScript will show an error if you try to use a component with a mismatched field type.

Migrating from the legacy settings API

Apps created before the folder-based layout define settings with an app.settings.ts schema and a Page registered in app.ts. That API is deprecated. Settings cannot be defined both ways at once (doing so is a build error), so migrate settings in one step, either with attio migrate folder-structure or by hand.

Adding workspace settings guide - step-by-step guide
Settings form components - available form components

AttioIcon Settings.defineWorkspaceSchema()

⌘I

Introduction

Guides

Extensions

Workflow blocks

Notifications

Dialogs

Components

Forms

Icons

Settings

GraphQL

Data fetching

Server

System

Legacy

Example

Reading and writing settings

Type safety

Migrating from the legacy settings API

​Example

​Reading and writing settings

​Type safety

​Migrating from the legacy settings API

​Related

Example

Reading and writing settings

Type safety

Migrating from the legacy settings API

Related