Newbie Paintball Master

    react-native-save-base-sixty-four
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.3 • Public • Published

    react-native-save-base-sixty-four

    Allows you to save a base64-encoded image to your Photos or share it via the native share sheet.

    About this module

    This module was developed specifically for working with base64 encoded images, with an emphasis on Android support.

    If you are only looking for share sheet functionality, I would recommend using react-native-share. It supports base64 strings out of the box with no additional work.

    If you are looking for the ability to save a base64 string to the camera roll, specifically with support for the current version of Android as well as legacy versions of Android, this module will help you with that.

    Android support

    This module provides support for:

    • Scoped storage in Android Q
    • Legacy storage in versions of Android older than Q

    Please also note the permission checking in the example app as requesting and verifying permissions differs between Q and older versions of Android.

    When a user does not accept permissions, a few things happen:

    • On Android Q and above:
      • The user can share via the share sheet
      • Saving to device is successful
    • On older versions of Android:
      • Sharing via the share sheet crashes due to lack of permission
      • Saving to device crashes due to lack of permission

    For the above reasons, it's recommended to check for permissions on Android before performing any operations that require them, specifically on older versions of Android. See the Managing Permissions section below for an example.

    iOS support

    When a user does not accept permissions:

    • When attempting to share via the share sheet:
      • Sharing is successful (no permissions required for this action)
    • When attempting to save:
      • The promise will resolve with a value of false so you can handle the failure as expected due to the user not granting permission

    Installation

    npm install react-native-save-base-sixty-four --save
    yarn add react-native-save-base-sixty-four

    iOS

    Add this to your Info.plist:

    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>Save photo to device</string>

    The <string> value above can be anything you like—this will be the message that shows up when the user is prompted to allow photo access.

    Android

    Add this to your AndroidManifest.xml:

    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="28" />

    Usage

    Call either the share or save method with the base64 encoded string and optional options for Android.

    share(base64ImageString: string, options: SaveBase64ImageOptions)

    import SaveBase64Image from 'react-native-save-base-sixty-four';
    
    // Native share sheet
    //    with async await
    try {
      const success = await SaveBase64Image.share(base64ImageString, options);
      if (!success) {
        // 😭 user did not grant permission
      }
    } catch (error) {
      // 💥 there was a crash
    }
    
    //    with promises
    SaveBase64Image
      .share(base64ImageString, options)
      .then((success) => {
        if (!success) {
          // 😭 user did not grant permission
        }
      })
      .catch((error) => {
        // 💥 there was a crash
      });

    save(base64ImageString: string, options: SaveBase64ImageOptions)

    import SaveBase64Image from 'react-native-save-base-sixty-four';
    
    // Save to device
    //    with async await
    try {
      const success = await SaveBase64Image.save(base64ImageString, options);
      if (!success) {
        // 😭 user did not grant permission
      }
    } catch (error) {
      // 💥 there was a crash
    }
    
    //    with promises
    SaveBase64Image
      .save(base64ImageString, options)
      .then((success) => {
        if (!success) {
          // 😭 user did not grant permission
        }
      })
      .catch((error) => {
        // 💥 there was a crash
      });

    base64ImageString: string

    The base64 encoded string should not have the header, i.e. data:image/png;base64, (or similar) should be removed.

    options: SaveBase64ImageOptions

    The options below are used in the Android module:

    interface SaveBase64ImageOptions {
      mimeType?: 'image/png' | 'image/jpg';
      quality?: number;
      fileName?: string;
    }
    • mimeType (default: 'image/png'): Android configuration of mime type for bitmap compression and for the share intent. Currently only supporting 'image/png' | 'image/jpg'
    • quality (default: 100): Bitmap compression quality on Android
    • fileName (default: 'image'): The filename for Android. This will be visible in the Photos app when saving and as the file name when sharing.

    Managing Permissions

    Here's an example implementation that uses the permissions code in the example app:

    const handleBase64Image = async (base64ImageString, fileName) => {
      const imageWithoutHeader = base64ImageString.replace('data:image/png;base64,', '');
    
      if (Platform.OS === 'android') {
        const hasPermission = await hasStoragePermissions();
        if (!hasPermission) {
          Alert.alert('Fail', 'You need to give the app permission');
          return;
        }
      }
    
      const success = await SaveBase64Image.save(imageWithoutHeader, { fileName });
      Alert.alert(success ? '😄 Success' : '😞 Fail');
    };

    Contributing

    See the contributing guide to learn how to contribute to the repository and the development workflow.

    License

    MIT

    Install

    npm i react-native-save-base-sixty-four

    DownloadsWeekly Downloads

    9

    Version

    0.1.3

    License

    MIT

    Unpacked Size

    6.88 MB

    Total Files

    115

    Last publish

    Collaborators

    • tinaciousdesign