react-aspect-ratio
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.49 • Public • Published

    React Aspect Ratio

    reac aspect ratio


    npm gzip size downloads circleci
    This is a React implementation for aspect ratio placeholder preventing browser reflow before browser downloads and renders your component.

    Cumulative Layout Shift

    Demo

    Inspired by Thierry Koblentz

    Original idea from Sérgio Gomes

    You can also read a detail post by Chris Coyier

    Why

    Most common use case is image loading. If you are not define dimensions for your image tag, browser will assume its a square size of image before image loaded. Hence you will see browser reflow your layout (layout shift) after image loaded.

    If you define a hard dimensions, it might not fit a responsive design.

    How

    This library using a pseudo element to create space based on the aspect ratio. For browser supporting aspect-ratio property (Chromium 88, Firefox 87, and Safari Technology Preview 118), the style will be adopted to the pseudo element.

    Other browsers will be using what people call "Padding trick" - creating a wrapper html tag with zero height and a percentage of padding-bottom to perserve space. (padding-bottom will be percentage of your component width).

    This library also utilizes CSS variable for modern browser as well as CSS calc API to minimized the style needed for different padding value.

    Browser Support

    We replies on CSS custom property and CSS calc function.

    Installation

    via yarn

    $ yarn add react-aspect-ratio
    

    or via npm

    $ npm install react-aspect-ratio
    

    Usage

    Props

    Props Type Default Description
    ratio string/number 1 Aspect ratio of your component, could be number or string like width/height
    other props Object {style: {--aspect-ratio: ${ratio}} } Any props to your React component, the library will add --aspect-ratio to your style object
    children React Element Single DOM element

    You will need to import 'react-aspect-ratio/aspect-ratio.css'

    • Note
    import { AspectRatio } from 'react-aspect-ratio'; // Recommended: if you are using React > 15.6
    
    import AspectRatio from 'react-aspect-ratio'; // Deprecated: if you are using React <= 15.6
    import { AspectRatio } from 'react-aspect-ratio';
    
    const RatioImage = () => (
      <AspectRatio ratio="3/4" style={{ maxWidth: '400px' }}>
        <img src="https://c1.staticflickr.com/4/3896/14550191836_cc0675d906.jpg" />
      </AspectRatio>
    );
    import { AspectRatio } from 'react-aspect-ratio';
    
    const RatioIframe = () => (
      <AspectRatio ratio="560/315" style={{ maxWidth: '560px' }}>
        <iframe src="https://www.youtube.com/embed/Bku71V5f66g" frameBorder="0" allowFullScreen />
      </AspectRatio>
    );

    Can also use for background image

    import { AspectRatio } from 'react-aspect-ratio';
    
    <AspectRatio
      ratio={0.75}
      style={{
        maxWidth: '300px',
        backgroundImage: 'url(https://c1.staticflickr.com/4/3896/14550191836_cc0675d906.jpg)',
        backgroundSize: 'cover'
      }}
    />;

    CSS (Inspired by Thierry)

    [style*="--aspect-ratio"] > :first-child {
      width: 100%;
    }
    
    [style*="--aspect-ratio"] > img {
      height: auto;
    }
    
    [style*="--aspect-ratio"] {
      position: relative;
    }
    
    [style*="--aspect-ratio"] > :first-child {
      position: absolute;
      top: 0;
      left: 0;
      height: 100%;
    }
    
    [style*="--aspect-ratio"]::before {
      content: "";
      display: block;
    }
    
    @supports not (aspect-ratio: 1/1) {
      [style*="--aspect-ratio"]::before {
        height: 0;
        padding-bottom: calc(100% / (var(--aspect-ratio)));
      }
    }
    @supports (aspect-ratio: 1/1) {
      [style*="--aspect-ratio"]::before {
        aspect-ratio: calc(var(--aspect-ratio));
      }
    }
    • We use [style*="--aspect-ratio"] as a hook to target the appropriate boxes
    • We stretch the inner box regardless of support for custom property
    • We make sure the height of images comes from their intrinsic ratio rather than their height attribute
    • We style the container as a containing block (so the inner box references that ancestor for its positioning)
    • We create a pseudo-element to be used with
      • native aspect-ratio property if browser supported
      • the “padding hack” (it is that element that creates the aspect ratio) for browser not supporting aspect-ratio
    • We use calc() and var() to calculate padding based on the value of the custom property
    • We style the inner box so it matches the dimensions of its containing block

    Install

    npm i react-aspect-ratio

    DownloadsWeekly Downloads

    3,157

    Version

    1.0.49

    License

    MIT

    Unpacked Size

    36.3 kB

    Total Files

    18

    Last publish

    Collaborators

    • avatar