diff --git a/docs/src/data/links.tsx b/docs/src/data/links.tsx index 61c2c64a271..21dc45efb8d 100644 --- a/docs/src/data/links.tsx +++ b/docs/src/data/links.tsx @@ -199,6 +199,13 @@ export const connectedComponents: ComponentNavItem[] = [ body: "Amplify UI Storage components allow you to store files in the cloud using Amplify's Storage category", platforms: ['react'], }, + { + href: '/connected-components/storage/storageimage', + label: 'Storage Image', + body: 'StorageImage component allows users to load an image managed by Amplify Storage.', + platforms: ['react'], + tertiary: true, + }, { href: '/connected-components/storage/storagemanager', label: 'Storage Manager', diff --git a/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/DefaultStorageImageExample.tsx b/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/DefaultStorageImageExample.tsx new file mode 100644 index 00000000000..9189dfaa338 --- /dev/null +++ b/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/DefaultStorageImageExample.tsx @@ -0,0 +1,5 @@ +import { StorageImage } from '@aws-amplify/ui-react-storage'; + +export const DefaultStorageImageExample = () => { + return ; +}; diff --git a/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/StorageImageErrorHandlingExample.tsx b/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/StorageImageErrorHandlingExample.tsx new file mode 100644 index 00000000000..e18c95d8a05 --- /dev/null +++ b/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/StorageImageErrorHandlingExample.tsx @@ -0,0 +1,13 @@ +import { StorageImage } from '@aws-amplify/ui-react-storage'; + +export const StorageImageErrorHandlingExample = () => { + return ( + console.error(error)} + /> + ); +}; diff --git a/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/index.ts b/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/index.ts new file mode 100644 index 00000000000..80c9129aadf --- /dev/null +++ b/docs/src/pages/[platform]/connected-components/storage/storageimage/examples/index.ts @@ -0,0 +1,2 @@ +export { DefaultStorageImageExample } from './DefaultStorageImageExample'; +export { StorageImageErrorHandlingExample } from './StorageImageErrorHandlingExample'; diff --git a/docs/src/pages/[platform]/connected-components/storage/storageimage/index.page.mdx b/docs/src/pages/[platform]/connected-components/storage/storageimage/index.page.mdx new file mode 100644 index 00000000000..f488969506f --- /dev/null +++ b/docs/src/pages/[platform]/connected-components/storage/storageimage/index.page.mdx @@ -0,0 +1,21 @@ +--- +title: Storage Image +description: The Storage Image lets you load images from Amplify Storage. +reactSource: packages/react-storage/src/components/StorageImage/StorageImage.tsx +supportedFrameworks: react +--- + +import { Fragment } from '@/components/Fragment'; +import { getCustomStaticPath } from "@/utils/getCustomStaticPath"; + +export async function getStaticPaths() { + return getCustomStaticPath(frontmatter.supportedFrameworks); +} + +{/* `getStaticProps` is required to prevent "Error: getStaticPaths was added without a getStaticProps. Without getStaticProps, getStaticPaths does nothing" */} + +export async function getStaticProps() { + return { props: {} } +} + +{({ platform }) => import(`./${platform}.mdx`)} diff --git a/docs/src/pages/[platform]/connected-components/storage/storageimage/props.ts b/docs/src/pages/[platform]/connected-components/storage/storageimage/props.ts new file mode 100644 index 00000000000..cb76578e761 --- /dev/null +++ b/docs/src/pages/[platform]/connected-components/storage/storageimage/props.ts @@ -0,0 +1,35 @@ +export const STORAGE_IMAGE = [ + { + name: 'alt', + description: 'Alternative text description of the image', + type: 'string', + }, + { + name: 'imgKey', + description: 'The key of an image.', + type: 'string', + }, + { + name: 'accessLevel', + description: + 'Access level for files in Storage. See https://docs.amplify.aws/lib/storage/configureaccess/q/platform/js/', + type: `'public' | 'private' | 'protected'`, + }, + { + name: 'identityId?', + description: + 'The unique Amazon Cognito Identity ID of the image owner. Required when loading a protected image.', + type: 'string', + }, + { + name: 'fallbackSrc?', + description: + 'A fallback image source to be loaded when the component fails to load the image from Storage', + type: 'string', + }, + { + name: 'onStorageGetError?', + description: 'Triggered when an error happens calling Storage.get', + type: `(error: Error) => void;`, + }, +]; diff --git a/docs/src/pages/[platform]/connected-components/storage/storageimage/react.mdx b/docs/src/pages/[platform]/connected-components/storage/storageimage/react.mdx new file mode 100644 index 00000000000..19dfae813a9 --- /dev/null +++ b/docs/src/pages/[platform]/connected-components/storage/storageimage/react.mdx @@ -0,0 +1,67 @@ +import { Alert, Image } from '@aws-amplify/ui-react'; + +import { ComponentStyleDisplay } from '@/components/ComponentStyleDisplay'; +import { Example, ExampleCode } from '@/components/Example'; +import { Fragment } from '@/components/Fragment'; +import { AppDirectoryAlert } from '@/components/AppDirectoryAlert'; +import { InstallScripts } from '@/components/InstallScripts'; +import ReactPropsTable from '@/components/propsTable/ReactPropsTable'; +import { STORAGE_IMAGE } from './props'; +import { + DefaultStorageImageExample, + StorageImageErrorHandlingExample +} from './examples' + +## Basic Usage + + + Did you follow the [quick start instructions](/connected-components/storage#quick-start) to set up the storage and auth services? + + + + {({ platform }) => import('@/components/AppDirectoryAlert')} + + +To use the StorageImage component, import it into your React application with the included styles. + + + + +```js +import { StorageImage } from '@aws-amplify/ui-react-storage'; +import '@aws-amplify/ui-react/styles.css'; +``` + + +At a minimum you must include the `alt`, `imgKey` and `accessLevel` props. `accessLevel` refers to the [Amplify Storage access level](https://docs.amplify.aws/lib/storage/configureaccess/q/platform/js/), which is `'public' | 'private' | 'protected'`. + + + cat + + ```jsx file=./examples/DefaultStorageImageExample.tsx + ``` + + + +## Props + + + +Note: A new `Storage.get` request is made only when the `imgKey` changes. + +## Error Handling + +To handle the error caused by `Storage.get`, you can pass a `onStorageGetError` handler and optionally provide a `fallbackSrc` for the component to load a fallback image. + + + fallback cat + + ```jsx file=./examples/StorageImageErrorHandlingExample.tsx + ``` + + + +## Customization + +### Target Classes + diff --git a/packages/react/src/primitives/shared/constants.ts b/packages/react/src/primitives/shared/constants.ts index 535ab61287b..6c8e827df33 100644 --- a/packages/react/src/primitives/shared/constants.ts +++ b/packages/react/src/primitives/shared/constants.ts @@ -551,6 +551,7 @@ export const ComponentClassObject: ComponentClassNameItems = { StorageImage: { className: ComponentClassName.StorageImage, components: ['StorageImage'], + description: 'Class applied to the img tag', }, StorageManager: { className: ComponentClassName.StorageManager,