@twicpics/components

    0.4.1 • Public • Published

    TwicPics Components

    NPM Version License

    TwicPics Components

    What is TwicPics?

    TwicPics is a Responsive Image Service Solution (SaaS) that enables on-demand responsive image generation.

    With TwicPics, developers only deal with high-resolution versions of their media while end-users receive optimized, perfectly sized, device-adapted versions delivered from a server close to them.

    TwicPics acts as an image proxy. It requests your master image, be it on your own web server, cloud storage or DAM, then generates a device-adapted version with best-in-class compression, delivered directly to the end-user from the closest delivery point available.

    What is TwicPics Components?

    TwicPics Components is a collection of web components that make it dead easy to unleash the power of TwicPics in your own projects and using the framework of your choice.

    TwicPics Components currently supports:

    Installation

    TwicPics Components comes in the form of an NPM package.

    To add the package to your project, type one of:

    • npm add @twicpics/components
    • yarn add @twicpics/components

    depending on which package manager you fancy.

    Setup and Usage

    While we recommend going the ES module route and use import statements, TwicPics Components is also backward compatible with CommonJS and require statements.

    React

    main.jsx

    import React from "react";
    import ReactDOM from "react-dom";
    
    import Root from "./root.jsx";
    
    import { installTwicPics } from "@twicpics/components/react";
    import "@twicpics/components/style.css";
    
    installTwicPics( {
      "domain": "https://<your-domain>.twic.pics"
    } );
    
    ReactDOM.render(
      <React.StrictMode>
        <Root />
      </React.StrictMode>,
      document.getElementById( "root" )
    );

    root.jsx

    import React from "react";
    
    import { TwicImg } from "@twicpics/components/react";
    
    const Root = () => (
      <TwicImg src="path/to/your/image"/>
    );
    
    export default Root;

    Svelte 3.x

    main.js

    import Root from "./root.svelte";
    
    import { installTwicPics } from "@twicpics/components/svelte3";
    import "@twicpics/components/style.css";
    
    installTwicPics( {
      "domain": `https://<your-domain>.twic.pics`
    } );
    
    export default new Root( {
      "target": document.getElementById( "root" ),
    } );

    root.svelte

    <script context="module">
      import { TwicImg } from "@twicpics/components/svelte3";
    </script>
    
    <TwicImg src="path/to/your/image"/>

    Vue 2.x

    main.js

    import Vue from "vue";
    
    import Root from "./root.vue";
    
    import TwicPics from "@twicpics/components/vue2";
    import "@twicpics/components/style.css";
    
    Vue.use( TwicPics, {
      "domain": "https://<your-domain>.twic.pics"
    } );
    
    new Vue( {
      "render": h => h( Root ),
    } ).$mount( `#root` );

    root.vue

    <template>
      <TwicImg src="path/to/your/image"/>
    </template>

    Changing components names

    You can change how components are named using the TwicImg and/or TwicVideo options when calling use:

    Vue.use( TwicPics, {
      "domain": "https://<your-domain>.twic.pics",
      "TwicImg": "Batman"
    } );

    You can then reference the component using the alternate name:

    <template>
      <Batman src="path/to/your/image"/>
    </template>

    Vue 3.x

    main.js

    import { createApp } from "vue";
    
    import Root from "./root.vue";
    
    import TwicPics from "@twicpics/components/vue3";
    import "@twicpics/components/style.css";
    
    const app = createApp( Root );
    
    app.use( TwicPics, {
      "domain": `https://<your-domain>.twic.pics`
    } );
    
    app.mount( `#root` );

    root.vue

    <template>
      <TwicImg src="path/to/your/image"/>
    </template>

    Changing components names

    You can change how components are named using the TwicImg and/or TwicVideo options when calling use:

    app.use( TwicPics, {
      "domain": "https://<your-domain>.twic.pics",
      "TwicImg": "Batman"
    } );

    You can then reference the component using the alternate name:

    <template>
      <Batman src="path/to/your/image"/>
    </template>

    Web Components

    WARNING: every single Shadow DOM the TwicPics components are descendants of must be opened. That's the only way the TwicPics Script will be able to reach them.

    index.js

    import { installTwicPics, TwicImg } from "@twicpics/components/webcomponents";
    
    installTwicPics( {
      "domain": `https://<your-domain>.twic.pics`
    } );
    
    customElements.define( `twic-img`, TwicImg );

    index.html

    <body>
      <twic-img src="path/to/your/image"/>
    </body>

    Setup Options

    Option Description Type Default Required
    anticipation TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. Number 0.2
    domain This is your very own TwicPics domain. String
    maxDPR TwicPics will take the "Device Pixel Ratio" (DPR) of the current device into consideration when determining the sizes of images to load. By default, it will not take a DPR greater than 2 into consideration. If the DPR of the device is higher than 2, TwicPics will assume it to be 2. Using maxDPR, you can lower this limit down to 1 or be more permissive (for instance by setting it to 3 or 4). Number 2
    step To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. Integer 10

    Components

    The exact same components are available in all supported frameworks.

    TwicImg

    This component can be used in place of an img element.

    <TwicImg
      src="<path>"
      alt="<string>"
      ratio="<ratio>"
      width="<integer>"
      height="<integer>"
      mode="<contain|cover>"
      focus="<auto|coordinates>"
      position="<css position>"
      placeholder="<none|preview|meancolor|maincolor>"
      transition="<boolean>"
      transitionDelay="<String>"
      transitionDuration="<String>"
      transitionTimingFunction="<String>"
      step="<integer>"
    />
    Attribute Description Type Default Required
    alt alt attribute content String src based
    focus Only useful in cover mode. Can be auto or coordinates. See the TwicPics focus attribute documentation for more information. String 10
    height See ratio. Integer
    mode Can be contain or cover and determines if the image fills the area and is cropped accordingly (cover) or if the image will sit inside the area with no cropping (contain). String cover
    placeholder Can be preview, meancolor, maincolor or none. See the TwicPics output transformation documentation for more information. String preview
    position Only useful in contain mode. Locates the image inside the area. Syntax is the same as for CSS position properties like background-position or object-position. Useful values are top, bottom, left, right, left top, left bottom and so on. String center
    ratio Unitless width/height value pair. You can either use ratio or width and height to set the aspect-ratio of the area your image will be in. If both are used, ratio wins. A squared area will be created by default. String 1/1
    src Path to the image. String
    step See the TwicPics step attribute documentation for more information. Integer 10
    transition Whether or not to reveal images with a fade in effect once they have been loaded. Boolean true
    transitionDuration Duration of the transition effect. String 400ms
    transitionTimingFunction CSS timing function applied to the transition effect. String ease
    transitionDelay Transition delay of the transition effect. String 0ms
    width See ratio. Integer

    TwicVideo

    This component can be used in place of a video element.

    <TwicVideo
      src="<path>"
      ratio="<ratio>"
      width="<integer>"
      height="<integer>"
      mode="<contain|cover>"
      focus="<auto|coordinates>"
      position="<css position>"
      placeholder="<none|preview|meancolor|maincolor>"
      transition="<boolean>"
      transitionDelay="<String>"
      transitionDuration="<String>"
      transitionTimingFunction="<String>"
      step="<integer>"
    />
    Attribute Description Type Default Required
    focus Only useful in cover mode. Can be auto or coordinates. See the TwicPics focus attribute documentation for more information. String 10
    height See ratio. Integer
    mode Can be contain or cover and determines if the image fills the area and is cropped accordingly (cover) or if the image will sit inside the area with no cropping (contain). String cover
    placeholder Can be preview, meancolor, maincolor or none. See the TwicPics output transformation documentation for more information. String preview
    position Only useful in contain mode. Locates the image inside the area. Syntax is the same as for CSS position properties like background-position or object-position. Useful values are top, bottom, left, right, left top, left bottom and so on. String center
    ratio Unitless width/height value pair. You can either use ratio or width and height to set the aspect-ratio of the area your image will be in. If both are used, ratio wins. A squared area will be created by default. String 1/1
    src Path to the video. String
    step See the TwicPics step attribute documentation for more information. Integer 10
    transition Whether or not to reveal images with a fade in effect once they have been loaded. Boolean true
    transitionDuration Duration of the transition effect. String 400ms
    transitionTimingFunction CSS timing function applied to the transition effect. String ease
    transitionDelay Transition delay of the transition effect. String 0ms
    width See ratio. Integer

    Example

    You can find usage examples for all supported frameworks here.

    Install

    npm i @twicpics/components

    DownloadsWeekly Downloads

    37

    Version

    0.4.1

    License

    MIT

    Unpacked Size

    299 kB

    Total Files

    34

    Last publish

    Collaborators

    • florentb
    • jaubourg
    • balda