Organization Components | Sylphx Documentation

OrganizationProfile

View and edit organization details, logo, and settings

CreateOrganization

Form to create new organizations with validation

OrganizationList

List and switch between organizations

Quick Start

All organization components are available from the SDK. Wrap your app with SylphxProvider for automatic organization context.

Installation

import {
  OrganizationProfile,
  CreateOrganization,
  OrganizationList,
} from '@sylphx/platform-sdk/react'

OrganizationProfile

A complete organization profile management component with logo upload, name editing, and settings. Handles all update operations automatically.

Accessible

Themeable

Logo Upload

Basic Usage

import { OrganizationProfile } from '@sylphx/platform-sdk/react'

export default function SettingsPage() {
  return (
    <div className="max-w-2xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Organization Settings</h1>
      <OrganizationProfile
        onUpdate={(org) => {
          toast.success('Organization updated!')
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`onUpdate`	`(org: Organization) => void`	Callback fired after organization update
`onError`	`(error: Error) => void`	Callback fired on update error
`showLogo`	`boolean`= true	Show logo upload section
`showName`	`boolean`= true	Show organization name field
`showSlug`	`boolean`= true	Show URL slug field
`showDescription`	`boolean`= true	Show description field
`showWebsite`	`boolean`= true	Show website URL field
`showSettings`	`boolean`= true	Show organization settings
`showDangerZone`	`boolean`= false	Show danger zone with delete option
`allowSlugChange`	`boolean`= false	Allow changing the URL slug
`maxLogoSize`	`number`= 5242880	Max logo file size in bytes
`acceptedImageTypes`	`string[]`= ["image/jpeg", "image/png", "image/webp"]	Accepted image MIME types
`requiredRole`	`OrganizationRole`= "admin"	Minimum role required to edit
`layout`	`"card" \| "flat"`= "card"	Visual layout style
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<OrganizationProfile
  showLogo={true}
  showName={true}
  showSlug={true}
  showDescription={true}
  showWebsite={true}
  showSettings={true}
  showDangerZone={true}
  requiredRole="super_admin"
  onUpdate={(org) => {
    analytics.track('organization_updated', {
      orgId: org.id,
      changes: Object.keys(org),
    })
    toast.success('Settings saved!')
  }}
  onError={(error) => {
    if (error.code === 'SLUG_TAKEN') {
      toast.error('This URL is already taken')
    } else {
      toast.error('Failed to update organization')
    }
  }}
/>

Role Permissions

Only users with the required role (default: admin) will see edit controls. Others will see a read-only view.

CreateOrganization

A form component to create new organizations with name, slug, and optional logo. Handles validation, slug generation, and error states automatically.

Validation

Auto Slug

Basic Usage

import { CreateOrganization } from '@sylphx/platform-sdk/react'

export default function NewOrganizationPage() {
  return (
    <div className="max-w-md mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Create Organization</h1>
      <CreateOrganization
        onSuccess={(org) => {
          toast.success(`${org.name} created!`)
          router.push(`/org/${org.slug}/dashboard`)
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`onSuccess`	`(org: Organization) => void`	Callback fired after successful creation
`onError`	`(error: Error) => void`	Callback fired on creation error
`onCancel`	`() => void`	Callback fired when cancel button is clicked
`redirectUrl`	`string`	URL to redirect after creation
`showLogo`	`boolean`= true	Show logo upload field
`showDescription`	`boolean`= true	Show description field
`showSlug`	`boolean`= true	Show URL slug field
`autoGenerateSlug`	`boolean`= true	Auto-generate slug from name
`showCancelButton`	`boolean`= false	Show cancel button
`defaultValues`	`Partial<CreateOrgData>`	Pre-fill form with default values
`title`	`string`= "Create Organization"	Form title
`description`	`string`	Form description text
`submitLabel`	`string`= "Create Organization"	Submit button text
`cancelLabel`	`string`= "Cancel"	Cancel button text
`maxNameLength`	`number`= 100	Maximum organization name length
`maxSlugLength`	`number`= 50	Maximum slug length
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<CreateOrganization
  showLogo={true}
  showDescription={true}
  showSlug={true}
  showCancelButton={true}
  title="Start Your Team"
  description="Create a workspace for your team to collaborate"
  submitLabel="Get Started"
  cancelLabel="Go Back"
  onSuccess={(org) => {
    // Track creation
    analytics.track('organization_created', {
      orgId: org.id,
      name: org.name,
    })
    // Redirect to setup
    router.push(`/org/${org.slug}/setup`)
  }}
  onCancel={() => {
    router.back()
  }}
  onError={(error) => {
    if (error.code === 'SLUG_TAKEN') {
      toast.error('This URL is already taken, try another name')
    } else if (error.code === 'LIMIT_REACHED') {
      toast.error('You\'ve reached the maximum number of organizations')
    }
  }}
/>

Automatic Slug Generation

When autoGenerateSlug is enabled, the slug is automatically generated from the organization name. Users can still customize it before submission.

OrganizationList

Display all organizations the user belongs to with the ability to switch between them. Perfect for navigation sidebars, dropdowns, or dedicated organization switcher pages.

Switchable

Role Display

Active Indicator

Basic Usage

import { OrganizationList } from '@sylphx/platform-sdk/react'

export default function OrganizationSwitcherPage() {
  return (
    <div className="max-w-md mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Your Organizations</h1>
      <OrganizationList
        onSelect={(org) => {
          toast.success(`Switched to ${org.name}`)
          router.push('/dashboard')
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`onSelect`	`(org: Organization) => void`	Callback fired when an organization is selected
`onCreate`	`() => void`	Callback fired when create button is clicked
`showCreateButton`	`boolean`= true	Show create organization button
`showRole`	`boolean`= true	Show user role in each org
`showMemberCount`	`boolean`= false	Show member count
`showLogo`	`boolean`= true	Show organization logos
`showActiveIndicator`	`boolean`= true	Highlight the active organization
`showDescription`	`boolean`= false	Show organization descriptions
`createButtonLabel`	`string`= "Create Organization"	Create button text
`emptyState`	`ReactNode`	Custom empty state component
`layout`	`"list" \| "grid" \| "compact"`= "list"	Visual layout
`maxVisible`	`number`	Max orgs to show before "show more"
`sortBy`	`"name" \| "recent" \| "role"`= "recent"	Sort order
`filterRole`	`OrganizationRole[]`	Only show orgs with these roles
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<OrganizationList
  layout="compact"
  showRole={false}
  showMemberCount={false}
  showCreateButton={true}
  showActiveIndicator={true}
  maxVisible={5}
  onSelect={(org) => {
    // Just switch, don't navigate
    toast.success(`Now in ${org.name}`)
  }}
  onCreate={() => {
    router.push('/organizations/new')
  }}
  className="w-64"
/>

Theming

All organization components support theming via the theme prop. Customize colors, fonts, and styling to match your brand.

Custom Theme

import {
  OrganizationProfile,
  CreateOrganization,
  OrganizationList,
  defaultTheme,
  type ThemeVariables
} from '@sylphx/platform-sdk/react'

const customTheme: ThemeVariables = {
  ...defaultTheme,
  colorPrimary: '#6366f1',
  colorPrimaryHover: '#4f46e5',
  colorBackground: '#ffffff',
  colorForeground: '#1f2937',
  colorMuted: '#f3f4f6',
  colorMutedForeground: '#6b7280',
  colorBorder: '#e5e7eb',
  fontFamily: 'Inter, sans-serif',
  borderRadius: '0.75rem',
}

// Apply to all organization components
<OrganizationProfile theme={customTheme} />
<CreateOrganization theme={customTheme} />
<OrganizationList theme={customTheme} />

Property	Type	Description
`colorPrimary`	`string`= #000000	Primary brand color
`colorPrimaryHover`	`string`= #1f2937	Primary color on hover
`colorBackground`	`string`= #ffffff	Component background
`colorForeground`	`string`= #1f2937	Primary text color
`colorMuted`	`string`= #f3f4f6	Muted background
`colorMutedForeground`	`string`= #6b7280	Secondary text color
`colorBorder`	`string`= #e5e7eb	Border color
`colorDestructive`	`string`= #ef4444	Error/destructive color
`colorSuccess`	`string`= #22c55e	Success color
`fontFamily`	`string`= system-ui	Font family
`borderRadius`	`string`= 0.5rem	Border radius

Best Practices

Wrap with SylphxProvider

Ensure your app is wrapped with SylphxProvider for automatic organization context.

Handle Role Permissions

Components automatically respect role permissions. Non-admins see read-only views.

Provide Error Callbacks

Always provide onError callbacks to show user-friendly error messages.

Consider Empty States

Use the emptyState prop on OrganizationList to guide new users.

Need more customization?

Use the organization hooks for fully custom UI while keeping all the functionality.

Organizations Guide Auth Components

Organizations Guide

Hooks and server-side usage

Billing Plans

Per-organization subscriptions