Skip to content

Latest commit

 

History

History
316 lines (254 loc) · 9.8 KB

README.md

File metadata and controls

316 lines (254 loc) · 9.8 KB
Raw

⚠️ This documentation is for react-native-render-html v6 (@native-html/table-plugin@4.x). For v5 and below, go here.

@native-html/table-plugin

npm semver codecov CI DL/month Discord

🔠 A WebView-based plugin to render tables in react-native-render-html. 

npm add --save @native-html/table-plugin
yarn add @native-html/table-plugin

Features:

  • Render HTML tables with a WebView component you provide;
  • Supports HTML.onLinkPress prop to handle clicks;
  • Automatic height;
  • Customize table style with ease.

Known Limitations:

  • Don't forget you're rendering cells inside a webview, so you won't be able to apply your custom renderers there
  • Limited support of Expo <33 version ; full support ≥33 versions (see bellow limitation)
  • Autoheight behavior and onLinkPress config options only work with WebView ≥ v5.0.0 community edition

Compat Table

⚠️ The API is significantly different depending on target react-native-render-html version. Make sure you check the appropriate version documentation before proceeding.

react-native-render-html @native-html/table-plugin
≥ 4.2.1 < 5.0.0 2.x (documentation)
≥ 5.0.0 < 6.0.0 3.x (documentation)
≥ 6.0.0 4.x (documentation)
5.x (documentation)

Minimal working example

Full example

You need 2 steps to get to a working example:

  1. Import the WebView component. Instructions will differ depending on your setup;
  2. Inject renderers, customHTMLElementModels and WebView props to the HTML component;
import React from 'react';
import { ScrollView } from 'react-native';
import HTML from 'react-native-render-html';
import TableRenderer, { tableModel } from '@native-html/table-plugin';
import WebView from 'react-native-webview';

const html = `
<table>
  <tr>
    <th>Entry Header 1</th>
    <th>Entry Header 2</th>
  </tr>
  <tr>
    <td>Entry First Line 1</td>
    <td>Entry First Line 2</td>
  </tr>
</table>
`;

const htmlProps = {
  WebView,
  renderers: {
    table: TableRenderer
  },
  renderersProps: {
    table: {
      // Put the table config here
    }
  },
  customHTMLElementModels: {
    table: tableModel
  }
};

export const Example = () => (
  <ScrollView>
    <HTML source={{ html }} {...htmlProps} />
  </ScrollView>
);

API Reference

The complete API reference is available here: docs/table-plugin.md. Most notably, check TableConfig to see how you can customize the table behavior.

Landmark exports:

Other exports:

Troubleshooting

Errors when importing WebView component

⚠️ Always favor react-native-community/react-native-webview over legacy WebView when possible.

Setting up WebView component largely vary on your react-native or expo version. Please refer to the official documentation and make sure you have selected your RN / Expo SDK version:

FAQ

How to easily style the table?

Use TableConfig.tableStyleSpecs. The options will get merged with defaults, so you are not required to pass every field. See documentation.

import TableRenderer {
  defaultTableStylesSpecs,
  cssRulesFromSpecs
} from '@native-html/table-plugin';

const htmlProps = {
  renderers: { table: TableRenderer },
  renderersProps: {
    table: {
      tableStyleSpecs: {
        // my style specs
      }
    }
  }
};

How to disable autoheight?

Pass computeContainerHeight option with a function returning null:

import TableRenderer {
  defaultTableStylesSpecs,
  cssRulesFromSpecs
} from '@native-html/table-plugin';

const htmlProps = {
  renderers: { table: TableRenderer },
  renderersProps: {
    table: {
      computeContainerHeight() {
        return null;
      }
    }
  }
};

How to extend default or custom styles?

A: Use cssRulesFromSpecs function and override cssRules config.

import TableRenderer {
  defaultTableStylesSpecs,
  cssRulesFromSpecs
} from '@native-html/table-plugin';

const cssRules =
  cssRulesFromSpecs(defaultTableStylesSpecs) +
  `
a {
  text-transform: uppercase;
}
`;

const tableConfig = {
  cssRules
}

const htmlProps = {
  renderers: { table: TableRenderer },
  renderersProps: {
    table: {
      cssRules
    }
  }
};

How to customize the Table component?

A: See useHtmlTableProps hook. See custom example.

How to load custom fonts?

A: Extend styles and add @font-face rules.

import TableRenderer, {
  defaultTableStylesSpecs,
  cssRulesFromSpecs
} from '@native-html/table-plugin';
import { Platform } from 'react-native';

function getFontAssetURL(fontFileName: string) {
  return Platform.select({
    ios: `url(${fontFileName})`,
    android: `url(file://android_asset/fonts/${fontFileName})`
  });
}

const openSansUnicodeRanges =
  'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD';

const openSansRegular = getFontAssetURL('OpenSans-Regular.ttf');

const cssRules =
  cssRulesFromSpecs({
    ...defaultTableStylesSpecs,
    fontFamily: '"Open Sans"' // beware to quote font family name!
  }) +
  `
@font-face {
  font-family: 'Open Sans';
  font-style: normal;
  font-weight: 400;
  src: ${openSansRegular}, format('ttf');
  unicode-range: ${openSansUnicodeRanges};
}
`;

const htmlProps = {
  renderers: { table: TableRenderer },
  renderersProps: {
    table: {
      cssRules
    }
  }
};