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.
 * - Sanity WebP (auto=format): When the URL is served by the Sanity image CDN (cdn.sanity.io/images/) and is not an SVG, `auto=format` is appended to `src`, every `srcset` entry, `data-src`/`data-srcset`, and the lazy placeholder. The CDN serves WebP to browsers that support it and falls back to the original format otherwise. Non-Sanity URLs are left untouched.
 * - Fixed-px sizes: When `sizes` is a single fixed px value (e.g. "100px"), the srcset contains exactly that width plus a 2x variant for high-DPI/retina displays (`?w=100 100w, ?w=200 200w`), capped at the original asset width and deduped. Any other `sizes` value (vw, media queries, multiple entries) uses the standard candidate widths [1300, 1024, 810, 580].
 * - SVG Handling: SVG files are automatically detected and do not generate srcset, sizes, or any URL transform param (Sanity rasterizes SVGs when transform params are present), 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> or <button> based on the configuration. With no matching option, returns a <div> when children are passed (slot content may contain block elements) or a <p> when only a label is rendered.
 *
 * @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: <p>Default Content</p>

<ButtonLink payload={{ customClass: "card-class" }}><div>Card content</div></ButtonLink>
//Render as: <div class="card-class"><div>Card content</div></div>
//NOTE: The no-option fallback with children renders a <div> (not a <p>) because slot content may contain block-level elements, which the HTML parser would hoist out of a <p>, breaking the DOM structure.

Form fields

Form fields core components docs - WIP

Changelog

• 0.1.16: Fix ButtonLink no-option fallback breaking DOM structure when slot children contain block-level elements. 0.1.15 rendered the fallback as <p>, but <p> only allows phrasing content, so browsers auto-close it when they meet a <div> — hoisting the children out of the wrapper and leaving empty/orphan <p> tags. The fallback is now conditional: <div> when children are passed, <p> when only a label is rendered (keeping the 0.1.15 orphan-text fix for label-only usage).
• 0.1.15: Change ButtonLink fallback element from <div> to <p> when no option matches (no link/button behavior). Rendering the label inside a paragraph avoids orphan text nodes that crawlers flag, and keeps the same classes and slot/label behavior.
• 0.1.14: Add Sanity CDN WebP support and fixed-px srcset to Image component. Sanity-hosted non-SVG images get auto=format on src, srcset, data-src/data-srcset and lazy placeholder, so the CDN serves WebP to supporting browsers with original-format fallback. When sizes is a single fixed px value (e.g. "100px"), the srcset is the exact width plus a 2x retina variant, capped at the original asset width and deduped; other sizes values keep the standard candidate widths. Srcset URLs are built respecting existing query strings, SVGs never receive transform params (Sanity would rasterize them), and all frontmatter functions now have TypeScript parameter types (fixes implicit-any ts7006 warnings).
• 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.