Overview

Introduction

UsageComing soon

Theme

Layout

Box

ContainerComing soon

Flex

Grid

SectionComing soon

Typography

Components

BlockquoteComing soon

ComboboxComing soon

JSON Path SelectorComing soon

ZoomableComing soon

Formatting

CodeComing soon

EmComing soon

KbdComing soon

QuoteComing soon

StrongComing soon

Icons

Logo IconComing soon

Feature IconComing soon

Provider Icon

Icon Panel

Navigation

Page NavComing soon

Quick NavComing soon

Utilities

DS ProviderComing soon

Recipes

Copy Button

Copy Chip

Theme Toggle

Image Field

Displays an input that lets users upload an image and see its preview.

 <ImageField.Root>
  <ImageField.Preview />
</ImageField.Root>

Anatomy

Import the component and piece the parts together.

 import { ImageField } from '@workos-inc/design-system';

export default () => (
  <ImageField.Root>
    <ImageField.Preview />
  </ImageField.Root>
);

Props

ImageField.Root

`accept`

readonly ("image/jpeg" | "image/png" | "image/gif" | "image/svg+xml" | "image/webp" | "image/avif" | "image/x-icon" | "image/vnd.microsoft.icon")[] | ("image/jpeg" | "image/png" | "image/gif" | ... 4 more ... | "image/vnd.microsoft.icon")[]

`defaultFile`

string | File | null

`file`

string | File | null

`maxDimensions`

{ width: number; height: number; }

`maxSizeKB`

number

`minDimensions`

{ width: number; height: number; }

`name`

string

`placeholder`

string

`ratio`

number

`state`

disablednormalread-only

Also supports MarginProps: `m`, `mb`, `ml`, `mr`, `mt`, `mx`, `my`

ImageField.Preview

`backgroundColor`

string

`src`

string | null

Usage

Placeholder

A placeholder is rendered when no preview is displayed. Use the placeholder prop to change the default text.

 <ImageField.Root placeholder="Dark mode logo">
  <ImageField.Preview />
</ImageField.Root>

Controlled

Make the Root part controlled to access the uploaded file.

 () => {
  const [file, setFile] = React.useState(null);

  if (file) {
    console.log(file);
  }

  return (
    <ImageField.Root file={file} onFileChange={setFile}>
      <ImageField.Preview />
    </ImageField.Root>
  );
};

Use the onSrcChange prop to access the temporary URL of the preview image.

 () => {
  const [previewSrc, setPreviewSrc] = React.useState(null);

  if (previewSrc) {
    console.log(previewSrc);
  }

  return (
    <ImageField.Root>
      <ImageField.Preview onSrcChange={setPreviewSrc} />
    </ImageField.Root>
  );
};

Initial value

Use a URL for the defaultFile prop to create an uncontrolled field with an initial value.

 <ImageField.Root defaultFile="https://images.workoscdn.com/images/5b739c4b-22b3-4b0a-a2ee-c517264a8b25.svg">
  <ImageField.Preview />
</ImageField.Root>

Custom preview

You can render a custom preview layout if you pass a function as a child of the Preview part.

 <ImageField.Root defaultFile="https://images.workoscdn.com/brand/v2/favicon@32x32.png" placeholder="Upload favicon">
  <ImageField.Preview>
    {(src) => (
      <Flex align="center" gap="2">
        <img alt="" height="16" src={src} width="16" />
        <Text size="1">Favicon</Text>
      </Flex>
    )}
  </ImageField.Preivew>
</ImageField.Root>

Background color

Use the backgroundColor prop on the Preview part to set a background color on the preview image.

 <ImageField.Root defaultFile="https://images.workoscdn.com/images/3a07503a-41f6-4e27-80d4-7e2506d0afe8.svg">
  <ImageField.Preview backgroundColor="#000000" />
</ImageField.Root>

States

Use the state prop to create a disabled or read-only Image Field.

 <Grid columns="2" gap="3">
  <ImageField.Root state="disabled" placeholder="Disabled">
    <ImageField.Preview />
  </ImageField.Root>
  <ImageField.Root
    state="disabled"
    defaultFile="https://images.workoscdn.com/images/3a07503a-41f6-4e27-80d4-7e2506d0afe8.svg"
  >
    <ImageField.Preview backgroundColor="#000000" />
  </ImageField.Root>

  <ImageField.Root state="read-only" placeholder="Read-only">
    <ImageField.Preview />
  </ImageField.Root>
  <ImageField.Root
    state="read-only"
    defaultFile="https://images.workoscdn.com/images/3a07503a-41f6-4e27-80d4-7e2506d0afe8.svg"
  >
    <ImageField.Preview backgroundColor="#000000" />
  </ImageField.Root>
</Grid>

Validation

Use the available validation props to enforce constraints upon the uploaded images. Use the onError prop to access the errors.

 () => {
  const [errorMessages, setErrorMessages] = React.useState([]);
  return (
    <Box>
      <ImageField.Root
        accept={['image/png']}
        ratio={1}
        minDimensions={{ width: 100, height: 100 }}
        maxDimensions={{ width: 1000, height: 1000 }}
        maxSizeKB={100}
        onError={(errors) => {
          setErrorMessages(
            errors.map((error) => {
              switch (error) {
                case 'file-size-too-large':
                  return 'File size should not exceed 100 KB';
                case 'dimensions-too-small':
                  return `Image dimensions should be at least 100×100`;
                case 'dimensions-too-large':
                  return 'Image dimensions should not exceed 1000×1000';
                case 'aspect-ratio-incorrect':
                  return 'Image aspect ratio should be 1:1';
                case 'format-unacceptable':
                  return 'Only PNG images are allowed';
                case 'file-unreadable':
                  return 'Error processing the file';
              }
            }),
          );
        }}
      >
        <ImageField.Preview />
      </ImageField.Root>

      {errorMessages.map((message) => (
        <Text as="div" color="red" size="2" mt="2">
          {message}
        </Text>
      ))}
    </Box>
  );
};

Variants

Dashboard

2 variants found

ImageField in Edit Application Logo Dialogdashboardstatic

/:environmentId/applications/:applicationId

<ImageField.Root
      accept={VALID_LOGO_TYPES}
      aria-label={label}
      file={file === undefined ? logoUrl : file}
      maxSizeKB={MAX_LOGO_SIZE_KB}
      minDimensions={{ height: MIN_LOGO_DIMENSION, width: MIN_LOGO_DIMENSION }}
      name={name}
      placeholder={label}
      ratio={1}
      state={disabled ? 'disabled' : 'normal'}
      onError={onError}
      onFileChange={onFileChange}
    >
      <ImageField.Preview
        backgroundColor={theme === 'dark' ? 'var(--gray-1)' : '#ffffff'}
        src={previewSrc}
      />
    </ImageField.Root>

ImageField in Edit Application Logo Dialogdashboardstatic

/:environmentId/applications/:applicationId

<ImageField.Root
      accept={VALID_LOGO_TYPES}
      aria-label={label}
      file={file === undefined ? logoUrl : file}
      maxSizeKB={MAX_LOGO_SIZE_KB}
      minDimensions={{ height: MIN_LOGO_DIMENSION, width: MIN_LOGO_DIMENSION }}
      name={name}
      placeholder={label}
      ratio={1}
      state={disabled ? 'disabled' : 'normal'}
      onError={onError}
      onFileChange={onFileChange}
    >
      <ImageField.Preview
        backgroundColor={theme === 'dark' ? 'var(--gray-1)' : '#ffffff'}
        src={previewSrc}
      />
    </ImageField.Root>

Context

ImageField.Root

Prop	Type	Default	Required
`accept`	`readonly ("image/jpeg" \| "image/png" \| "image/gif" \| "image/svg+xml" \| "image/webp" \| "image/avif" \| "image/x-icon" \| "image/vnd.microsoft.icon")[] \| ("image/jpeg" \| "image/png" \| "image/gif" \| ... 4 more ... \| "image/vnd.microsoft.icon")[]`	—	no
`defaultFile`	`string \| File \| null`	—	no
`file`	`string \| File \| null`	—	no
`maxDimensions`	`{ width: number; height: number; }`	—	no
`maxSizeKB`	`number`	—	no
`minDimensions`	`{ width: number; height: number; }`	—	no
`name`	`string`	—	no
`placeholder`	`string`	—	no
`ratio`	`number`	—	no
`state`	`"disabled" \| "normal" \| "read-only"`	—	no

Also supports MarginProps: m, mb, ml, mr, mt, mx, my

ImageField.Preview

Prop	Type	Default	Required
`backgroundColor`	`string`	—	no
`src`	`string \| null`	—	no

Usage

Used 18 times across 1 package

Dashboard

Where it's used

3 files

/branding/edit

packages/dashboard/src/app/(private)/(chromeless)/branding/edit/edit-branding.tsx12

packages/dashboard/src/components/onboarding-flows/branding-onboarding-step-content.tsx4

/:environmentId/applications/:applicationId

packages/dashboard/src/app/(private)/(sidebar)/[environmentId]/applications/[applicationId]/edit-application-logo-dialog.tsx2

Image Field

On this page

Anatomy

Props

ImageField.Root

`accept`

`defaultFile`

`file`

`maxDimensions`

`maxSizeKB`

`minDimensions`

`name`

`placeholder`

`ratio`

`state`

ImageField.Preview

`backgroundColor`

`src`

Usage

Placeholder

Controlled

Initial value

Custom preview

Background color

States

Validation

Variants

Dashboard

Context

Full API Reference

ImageField.Root

ImageField.Preview

Usage Statistics

Usage

Where it's used