Astro core

astro-core is a collection of core Astro components designed to streamline asset management and simplify form creation in your Astro projects, among other features. These components provide a flexible, powerful set of tools for handling images, videos, form fields, buttons, anchor, external links, etc.

npm install @terrahq/astro-core

🚀 How to import

To use the components from astro-core, simply import them into your Astro project:

//Import example
import { Asset, ButtonLink } from "@terrahq/astro-core";

Components

Asset

/**
 * Renders an asset component (Image, Video, or Lottie) dynamically based on the type provided in the payload.
 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains asset data and options.
 * @param {string} Astro.props.payload.type - The type of the asset, which determines which component to render. Expected values are:
 *  - `"Image"`: Renders the `Image` component.
 *  - `"Video"`: Renders the `Video` component.
 *  - `"Lottie"`: Renders the `Lottie` component.
 *
 * @example Usage:
 */

<Asset
  payload={{
    type: "Image",
    url: "https://example.com/image.jpg",
    alt: "Example Image",
    customClass: "image-class",
  }}
/>

<Asset
  payload={{
    type: "Lottie",
    url: "https://example.com/animation.json",
    customClass: "my-lottie-animation",
    animType: "canvas",
    loop: true,
    autoplay: false,
    name: "myLottie"
  }}
/>

<Asset
  payload={{
    type: "Video",
    url: "https://example.com/video.mp4",
    customClass: "my-video",
    attributes: { controls: true, poster: "https://example.com/poster.jpg" },
    width: 1280,
    height: 720
  }}
/>

Type Image

/**
 * Renders an image element with lazy loading, aspect ratio, srcset, and other configurable attributes.
 * 
 * Dynamic Behavior:
 * - Lazy Loading: If `lazy` is `true`, the `data-src` and `data-srcset` attributes are used instead of `src` and `srcset`, enabling lazy loading.
 * - Aspect Ratio: If `aspectRatio` is `true` and both `width` and `height` are provided, an `aspect-ratio` style is applied to maintain the image's aspect ratio.
 * - Srcset: Automatically generates a `srcset` for responsive images if `width` is provided in the `attributes` and the image is not an SVG.
 * - SVG Handling: SVG files are automatically detected and do not generate srcset or require sizes attributes, preventing unnecessary responsive image processing.
 * - IMPORTANT: If you are using a custom backend, you need to use width and height attributes in the Image component if its a SVG.
 * - Sizes Validation: The "No sizes attribute provided" error only appears when a srcset is actually generated and sizes are missing, not for SVGs or images without srcset.

 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains image-related data and options.
 * @param {string} Astro.props.payload.url - The image URL.
 * @param {string} [Astro.props.payload.placeholderUrl] - The placeholder image URL for lazy loading.
 * @param {boolean} [Astro.props.payload.srcset] - The srcset attribute for responsive images. Default is `true`.
 * @param {string} [Astro.props.payload.sizes] - The sizes attribute for responsive images.
 * @param {string} [Astro.props.payload.alt] - The alt text for the image (important for accessibility).
 * @param {string} [Astro.props.payload.customClass] - Custom classes to apply to the image.
 * @param {boolean} [Astro.props.payload.lazy=false] - Enables lazy loading for the image. Default is `false`.
 * @param {string} [Astro.props.payload.lazyClass] - Custom class to apply to the image when lazy loading is enabled. Default is `"g--lazy-01"`.
 * @param {boolean} [Astro.props.payload.aspectRatio=true] - Enables aspect ratio styling for the image. Default is `true`.
 * @param {boolean|string} [Astro.props.payload.decodingAsync="auto"] - Determines image decoding behavior. Boolean: true="async", false="auto". String: "sync", "async", "auto". Default is `"auto"`.
 * @param {boolean|string} [Astro.props.payload.fetchPriority="auto"] - Determines image fetch priority. Boolean: true="high", false="auto". String: "high", "low", "auto". Default is `"auto"`.
 * @param {Object} [Astro.props.payload.attributes] - Additional image attributes like width, height, etc.
 *
 * @example Usage:
 */

 <Asset
   payload={{
     type: "Image",
     url: "https://example.com/image.jpg",
     sizes: "(max-width: 600px) 480px, 800px",
     alt: "Example image",
     customClass: "image-class",
     lazy: true,
     aspectRatio: true,
     decodingAsync: "async", // or true/false for backward compatibility
     fetchPriority: "high",  // or true/false for backward compatibility
     attributes: {
       width: 1024,
       height: 768
     }
   }}
 />

Type Video

/**
 * Renders a video component based on the `payload` properties.
 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains video data and options.
 * @param {boolean} Astro.props.payload.isBoostify - Whether the video uses Boostify integration.
 * @param {string} Astro.props.payload.video_type - The type of video source: "url" or "file".
 * @param {string} Astro.props.payload.video_url - The URL of the video (for embeds).
 * @param {string} Astro.props.payload.video_file - The file path of the video (for file-based rendering).
 * @param {string} Astro.props.payload.format - Video format (e.g., mp4).
 * @param {string} Astro.props.payload.poster_url - Poster image URL for the video.
 * @param {boolean} Astro.props.payload.hasPosterImg - Indicates if a poster image slot is provided.
 * @param {string} Astro.props.payload.customClass - Custom CSS class for styling.
 * @param {string} Astro.props.payload.boostifyClass - CSS class for Boostify integration.
 * @param {number} Astro.props.payload.width - Width of the video.
 * @param {number} Astro.props.payload.height - Height of the video.
 * 
 * @example Usage:
 */

<Asset
  payload={{
    type: "Video",    
    video_type: 'url',
    video_url: 'https://www.youtube.com/watch?v=your-video-id',
    customClass: 'video-class',
    isBoostify: false,
  }}
/>

<Asset
  payload={{
    type: "Video",    
    video_type: 'file',
    video_file: '/asset/video/placeholder.mp4',
    hasPosterImg: true,
    poster_url: 'https://example.com/image.jpg'
    customClass: 'video-class',
  }}
/>

Type Lottie

:warning: For lotties use dependency @terrahq/helpers.

/**
 * Renders a Lottie animation element using a `div` with custom data attributes.
 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains Lottie-related data and options.
 * @param {string} Astro.props.payload.url - The URL to the Lottie JSON animation file.
 * @param {string} [Astro.props.payload.customClass] - Custom classes to apply to the Lottie `div`.
 * @param {string} [Astro.props.payload.animType="svg"] - The type of animation format.
 * @param {boolean} [Astro.props.payload.loop=true] - Whether the animation should loop. Default is `true`.
 * @param {boolean} [Astro.props.payload.autoplay=true] - Whether the animation should start playing automatically. Default is `true`.
 * @param {string} [Astro.props.payload.name="lottie-asset"] - The name identifier for the Lottie animation instance. Default is `"lottie-asset"`.
 *
 * @example Usage:
 */

 <Asset
   payload={{
    type: "Lottie",
    url: "https://example.com/animation.json",
    customClass: "my-lottie-animation",
    loop: true,
    autoplay: false,
    name: "myLottie"
   }}
 />

Button Link

/**
 * @param {Object} payload - The configuration object for the link/button.
 * @param {string} [payload.href] - URL for external links.
 * @param {string} [payload.label] - Text label for the link/button (used if no children are passed).
 * @param {string} [payload.option='target_blank'] - Determines link behavior: 'target_self', 'target_blank', 'scroll_to_section', or 'open_modal'.
 * @param {string} [payload.section_id] - ID of the section to scroll to.
 * @param {string} [payload.ariaLabel] - Accessibility label for the link/button.
 * @param {string} [payload.customClass=''] - CSS class to apply to the rendered element.
 *
 * @returns {JSX.Element} - Returns an <a>, <button>, or <div> with a slot based on the configuration.
 *
 * @examples
 */

<ButtonLink payload={{ href: "/about-us", option: "target_self", customClass: "link-class", label: "About Us" }} />
// Render as: <a href="/about-us" class="link-class">About Us</a>
// NOTE: For Sanity projects, use getURL() helper function for internal links. See src/utilities/astro/getUrl.js  on Terra front repository for reference.

<ButtonLink payload={{ href: "https://example.com", option: "target_blank", customClass: "external-link", label: "Visit Example" }} />
//Render as: <a href="https://example.com" class="external-link" target="_blank">Visit Example</a>

<ButtonLink payload={{ option: "scroll_to_section", customClass: "scroll-button", label: "Scroll Down" }} />
//Render as: <button class="scroll-button">Scroll Down</button>

<ButtonLink payload={{ option: "button", customClass: "action-button", label: "Click Me" }} />
//Render as: <button class="action-button">Click Me</button>

<ButtonLink payload={{ label: "Default Content" }} />
//Render as: <div>Default Content</div>

Form fields

Form fields core components docs - WIP

Changelog

• 0.1.13: Fix sizes validation in Image component to respect srcset setting. When srcset: false is set, the "No sizes attribute provided" error no longer appears, allowing users to disable responsive images without validation warnings.
• 0.1.12: Update documentation adding that if you are using a custom backend, you need to use width and height attributes in the Image component if its a SVG.
• 0.1.11: Improve SVG handling in Image component. SVG files are now automatically detected and do not generate srcset or require sizes attributes. Fixed sizes validation error to only appear when srcset is actually generated, preventing false errors for SVGs and images without responsive processing.
• 0.1.10: Update decodingAsync and fetchPriority to accept both boolean and string values. New string options: decodingAsync ("sync", "async", "auto") and fetchPriority ("high", "low", "auto"). Default values changed to "auto" for both properties. Maintains backward compatibility with boolean values.
• 0.1.9: Fix lazy loading data-src, add optional srcset and custom lazy loading class.
• 0.1.8: Fix lazy attribute when is not inside attributes.
• 0.1.7: Upgrade to astro v5.
• 0.1.6: Fix srcset having larger sizes than width and add tooltip when sizes are not provided.
• 0.1.5: Rename option to choose target self/blank on Button Link instead of external/internal link naming.
• 0.1.4: Add name attribute to Textarea and Select input.
• 0.1.3: Add Textarea, Label and Select input to form-fields components.
• 0.1.2: Improve cleanAltText function to handle non-string inputs safely and prevent runtime errors.
• 0.1.1: Add helper function to handle cleanup of alt string
• 0.1.0: Remove modal option from button link and fix lazyloading default to false
• 0.0.8: Fix Video asset slot rendering.
• 0.0.7: Update lottie payload. Loop and name now convert boolean to string properly.
• 0.0.6: Update lottie payload with dynamic url, loop and name.