OverviewIntroductionIntroductionUsageUsageThemeThemeLayoutBoxBoxContainerContainerFlexFlex GridGridSectionSectionTypographyTextText HeadingHeadingComponentsAccordionAccordionAlert DialogAlert DialogAvatarAvatarBadgeBadgeBlockquoteBlockquoteButtonButton CalloutCallout CardCard CheckboxCheckbox ChipChip Code BlockCode Block Code EditorCode Editor Color FieldColor Field Data ListData ListDefinition ListDefinition ListDialogDialogHover CardHover CardIcon ButtonIcon Button InsetInset Image FieldImage Field LabelLabel MarkerMarkerPermanent LinkPermanent LinkPopoverPopoverProgressProgressRadio Card GroupRadio Card GroupScreenshotScreenshotScroll AreaScroll AreaSegmented ControlSegmented ControlSelectSelectSeparatorSeparator SkeletonSkeleton SpinnerSpinner StatusStatus SwitchSwitch TableTableTabsTabsText AreaText Area Text FieldText FieldTooltipTooltipZoomableZoomableFormattingCodeCodeEmEmKbdKbdQuoteQuoteStrongStrongIconsLogo IconLogo IconFeature IconFeature IconProvider IconProvider IconIcon PanelIcon PanelNavigationPage NavPage NavQuick NavQuick NavUtilitiesDesign System ProviderDesign System ProviderRecipesCopy ButtonCopy Button Copy ChipCopy Chip Theme ToggleTheme Toggle

Image Field

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

Upload image

 <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>
);

API Reference

The Image Field component is made up of Root and Preview. View source

Root

Displays a stylized image input field.

Prop	Type	Default
`defaultFile`	`File \| string \| null`	`–`
`file`	`File \| string \| null`	`–`
`onFileChange`	`(file: File \| null) => void`	`–`
`onError`	`(errors: ImageFieldError[]) => void`	`–`
`accept`	`ImageFieldMimeType[]`	`['image/jpeg', 'image/png', 'image/gif', 'image/svg+xml', 'image/webp', 'image/avif', 'image/x-icon', 'image/vnd.microsoft.icon']`
`maxSizeKB`	`number`	`–`
`maxDimensions`	`{ width: number; height: number }`	`–`
`minDimensions`	`{ width: number; height: number }`	`–`
`ratio`	`number`	`–`
`state`	`"normal" \| "disabled" \| "read-only"`	`"normal"`
`placeholder`	`string`	`"Upload image"`

The following errors may be returned by the onError function:

Error	Description
`"aspect-ratio-incorrect"`	The aspect ratio of the image doesn’t match the `ratio` value
`"dimensions-too-large"`	The width or height of the image exceed `maxDimensions`
`"dimensions-too-small"`	The width or height of the image fall short of `minDimensions`
`"file-size-too-large"`	The file size exceeds the `maxSizeKB` value
`"file-unreadable"`	The file could not be processed by the browser
`"format-unacceptable"`	The file format doesn’t match any of the `accept` values

This component is based on the div element and supports common margin props m, mx, my, ml, mr, mt, mb.

Preview

Displays a preview of the uploaded image.

Prop	Type	Default
`backgroundColor`	`string`	`–`
`onSrcChange`	`(src?: string) => void`	`–`
`children`	`(src: string) => React.ReactNode`	`–`

Interactions

Backspace

Pressing the Backspace key clears the Image Field contents and related errors.

Examples

Placeholder

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

Dark mode logo

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

Controlled

Make the Root part controlled to access the uploaded file.

Upload image

 () => {
  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.

Upload 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.

Disabled

Read-only

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

Upload image

 () => {
  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>
  );
};