Sana Assistant (online)
Table of Contents

ADK client components

From this page you will find out more information about components, specifically provided by Sana to be used in add-ons.

It is highly recommended to read about Sana ADK before proceeding with this page.

Warning

Currently this page is in development. So, not all components are described.

Module "webstore/sana/elements"

Row component

The Row component is a top level component of Sana grid layout. Sana uses a 12-column grid layout framework to provide adaptive design.

Component props:

  • as - element that will be rendered as the row, by default it's div
  • className - CSS class of the row
  • noGutters - specifies whether the row should have left and right margins and paddings, if the property is set to true, the row will have no margins and paddings
  • noWrap - specifies whether the items in the row are forced onto one line or can wrap onto multiple lines, if the property is set to true, items will not break onto multiple lines
  • mainAxisAlign - defines how to align items inside the row along the main axis in flex layout
  • crossAxisAlign - defines how to align items inside the row on the cross axis in flex layout
  • children - child component that will be rendered inside the row
  • ref - reference to the row component

Example:

const ContentBlock = () => {
  return (
    <Row
      as="section"
      className="row-element"
      mainAxisAlign="center"
    >
      Row content element
    </Row>
  );
};

Col component

The Col component is one of core components of Sana grid layout. Columns are used to organize and position content horizontally within the row.

Component props:

  • as - element that will be rendered as column, by default it's div
  • crossAxisAlign - defines how to align items inside the row on the cross axis in flex layout
  • className - CSS class of the column
  • xs - size of the column on the xs screen breakpoint, it can be set to a number or to an object
  • sm - size of the column on the sm screen breakpoint, it can be set to a number or to an object
  • md - size of the column on the md screen breakpoint, it can be set to a number or to an object
  • lg - size of the column on the lg screen breakpoint, it can be set to a number or to an object
  • xl - size of the column on the xl screen breakpoint, it can be set to a number or to an object

Column size object:

  • size - size of the column
  • order - order of the column
  • offset - defines margin of the column on the left

Example:

const ContentBlock = () => {
  return (
    <Row>
      <Col
        className="column"
        md={{ size: 6, order: 0 }}
      >
        First column element
      </Col>
      <Col
        className="column"
        md={{ size: 6, order: 1 }}
      >
        Second column element
      </Col>
    </Row>
  );
};

Container component

The Container allows to create wrapper for the content.

Component props:

  • as - element that will be rendered as column, by default it's div
  • className - CSS class of the container
  • children - child components that will be rendered inside the container
  • fluid - specifies whether container should have adaptive width

Example:

const ContentBlock = () => {
  return (
    <Container
      className="container-block"
      fluid
    >
      Content
    </Container>
  );
};

DomHead component

The <DomHead>component allows to add metadata in the end of the <head> element.

Component props:

  • content - HTML content that will be at the end of the <head> element

Example:

const ContentBlock = () => {
  return (
    <DomHead content="<title>Page Title</title>" />
  )
};

DomElement component

The DomElement component allows to render HTML content at the place of content block.

Component props:

  • content - HTML content that will be rendered at the place of content block

Example:

const ContentBlock = () => {
  const content = `
    <div>
      <h3>Title</h3>
      <p>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean eleifend et ligula vel porttitor.
        Nullam cursus elementum mi at dignissim. Mauris elementum pretium nisi non porttitor. Sed ac fringilla velit.
      </p>
      <button>Click</button>
    </div>
  `;

  return (
    <DomElement content={content} />
  );
};

DomBody component

The DomBody component allows to render HTML content in the end of the <body> element.

Component props:

  • content - HTML content that will be rendered in the end of the <body> element

Example:

const Component = () => {
  const content = `
    <footer>
      <img src="./images/footer.png" alt="Footer" />
      Page Footer
    </footer>
  `;

  return (
    <DomBody content={content} />
  );
};

Heading component

The component that represents heading.

Component props:

  • as - defines the level of the heading, if no value is provided it will be rendered as a div element
  • className - CSS class of the heading
  • children - child component that will be rendered inside the heading

Example:

const ContentBlock = () => {
  return (
    <>
      <Heading className="heading" as="h1">Heading h1</Heading>
      <Heading className="heading" as="h2">Heading h2</Heading>
      <Heading className="heading" as="h3">Heading h3</Heading>
      <Heading className="heading" as="h4">Heading h4</Heading>
      <Heading className="heading" as="h5">Heading h5</Heading>
      <Heading className="heading" as="h6">Heading h6</Heading>
    </>
  );
};

Button component

The button component.

Component props:

  • children - child components that will be rendered inside the button
  • size - size of the button component, by default it's md
  • icon - icon of the button, if not specified then the default icon will be rendered, if false the default icon won't be rendered
  • className - CSS class of the button

Example:

const ContentBlock = () => {
  const [value, setValue] = useState(0);

  const onClick = () => {
    setValue(value => value + 1);
  };

  return (
    <div>
      {value}
      <Button
        className="button"
        onClick={onClick}
        size="sm"
        icon={false}
      >
        Increment
      </Button>
    </div>
  );
};

DangerAlert component

The DangerAlert allows to display short error message.

Component props:

  • scrollOnAppear - specifies whether the browser window should be scrolled to the alert on appearance
  • children - child component that will be rendered inside the alert

Example:

const Component = () => {
  const success = useSelector(state => state.api.response.success);

  const handleClick = () => {
    preformApiRequest(Urls.TestData, { token });
  };

  return (
    <Container>
      <Button onClick={handleClick}>Request data from API</Button>
      {!success && <DangerAlert scrollOnAppear>Failed to request data from API.</DangerAlert>}
    </Container>
  );
};

InfoAlert component

The InfoAlert allows to display short informational message.

Component props:

  • scrollOnAppear - specifies whether the browser window should be scrolled to the alert on appearance
  • children - child component that will be rendered inside the alert

Example:

const Component = () => {
  const handleClick = () => {
    preformApiRequest(Urls.TestData, { token });
  };

  return (
    <Container>
      <Button onClick={handleClick}>Request data from API</Button>
      <InfoAlert>Click the button above to request data from API.</InfoAlert>
    </Container>
  );
};

WarningAlert component

The WarningAlert allows to display short warning message.

Component props:

  • scrollOnAppear - specifies whether the browser window should be scrolled to the alert on appearance
  • children - child component that will be rendered inside the alert

Example:

const Component = () => {
  const handleClick = () => {
    preformApiRequest(Urls.TestData, { token });
  };

  return (
    <Container>
      <Button onClick={handleClick}>Request data from API</Button>
      <WarningAlert>Only authorized users are allowed to request data from API.</WarningAlert>
    </Container>
  );
};

SuccessAlert component

The SuccessAlert allows to display short message that informs about successful action.

Component props:

  • scrollOnAppear - specifies whether the browser window should be scrolled to the alert on appearance
  • children - child component that will be rendered inside the alert

Example:

const Component = () => {
  const success = useSelector(state => state.api.response.success);

  const handleClick = () => {
    preformApiRequest(Urls.TestData, { token });
  };

  return (
    <Container>
      <Button onClick={handleClick}>Request data from API</Button>
      {success && <SuccessAlert scrollOnAppear>Data received successfully.</SuccessAlert>}
    </Container>
  );
};

The Link component allows to create hyperlink that leads to external or internal page.

Component props:

  • to - takes object or parameterless function that returns this object as argument, which is used for navigation
  • url - URL of the page the link leads to
  • ref - reference to the link component
  • disabled - allows to disable the link
  • children - child components that will be rendered inside the link
  • onClick - function that will be invoked when the link is clicked. The function can return boolean value, if it's false it will prevent from navigating to internal page
  • omitScroll - specifies whether the internal page should scroll up after navigation, if true the page will not scroll up

to object:

  • routeName - name of the internal page to which the link will lead
  • params - allows to provide parameters for the link

Example with direct link:

const ContentBlock = () => {
  return (
    <Link
      className={styles.link}
      url="https://support.sana-commerce.com/Content/Home.htm"
    >
      Sana Online Help
    </Link>
  );
};

Example with internal page link:

const ContentBlock = () => {
  return (
    <Link
      className={styles.link}
      to={{
        routeName: 'ProductGroupPage',
        params: { id: 'ITEMS' }
      }}
      url="https://test.example/en-us/items-link"
      omitScroll
      onClick={() => !app.offlineMode}
    >
      Items group
    </Link>
  );
};

The BackLink component allows to navigate back to the previous location.

Component props:

  • children - child components that will be rendered inside the link

Example:

const ContentBlock = () => {
  return (
    <BackLink>
      Back
    </BackLink>
  );
};

LinkButton component

The LinkButton component looks like a sana button but behaves like a link.

Component props:

  • to - takes object or parameterless function that returns this object as argument, which is used for navigation
  • url - URL of the page the button leads to
  • ref - reference to the button component
  • disabled - allows to disable the button
  • children - child components that will be rendered inside the button
  • onClick - function that will be invoked when the link is clicked. The function can return boolean value, if false it will prevent from navigating to internal page
  • omitScroll - specifies whether the internal page should scroll up after navigation, if true the page will not scroll up
  • size - size of the button, by default it's md
  • theme - defines which theme should be applied to the button, be default regular
  • icon - icon of the button, if not specified default icon will be rendered, if false default icon won't be rendered
  • iconOnLeft - allows to specify the position of the icon, if true the icon will be displayed to the left of the button
  • noContentWrapper - specifies whether to apply a wrapper to the button's content, the wrapper adds additional styles

to object:

  • routeName - name of the internal page to which the link will lead
  • params - allows to provide parameters for the link

Example:

const ContentBlock = () => {
  return (
    <LinkButton
      className={styles.link}
      url="https://support.sana-commerce.com/Content/Home.htm"
      iconOnLeft
      icon={<LinkIcon />}
      size="sm"
    >
      Sana Online Help
    </LinkButton>
  );
};

LazyImage

The LazyImage component allows to display image that will be loaded when it appears in the viewport.

Component props:

  • src - path to the image
  • placeholderSrc - path to the placeholder
  • placeholder - allows to specify placeholder as a component
  • placeholderClassName - CSS class for the placeholder
  • afterLoad - function that will be invoked after the image is loaded
  • beforeLoad - function that will be invoked before the image is loaded
  • className - attribute to specify CSS class of the image
  • wrapperClassName - attribute to specify CSS class of the wrapper that applies additional styles
  • height - height of the image
  • width - width of the image
  • visibleByDefault - determines whether the image should be loaded off the viewport
  • threshold - threshold in pixels, so the component starts loading before it appears in the viewport

Example:

const ContentBlock = () => {
  return (
    <LazyImage
      src={source}
      placeholder={<ImagePlaceholder />}
      className={styles.image}
      width="200em"
      height="100em"
      afterLoad={() => {
        console.info('Image is loaded');
      }}
    />
  );
};

ResponsiveLazyImage

The ResponsiveLazyImage component works the same way LazyImage does but it adjusts its size based on the screen size.

Component props:

  • src - path to the image
  • placeholderSrc - path to the placeholder
  • placeholderClassName - CSS class for the placeholder
  • afterLoad - function that will be invoked after the image is loaded
  • beforeLoad - function that will be invoked before the image is loaded
  • className - attribute to specify CSS class of the image
  • wrapperClassName - attribute to specify CSS class of the wrapper that applies additional styles
  • height - height of the image
  • width - width of the image
  • visibleByDefault - determines whether the image should be loaded off the viewport
  • threshold - threshold in pixels. So the component starts loading before it appears in the viewport

Example:

const ContentBlock = () => {
  return (
    <ResponsiveLazyImage
      src={imageSrc}
      placeholderSrc={placeholderSrc}
      className={styles.image}
      placeholderClassName={styles.placeholder}
      wrapperClassName={styles.imageWrapper}
      afterLoad={() => {
        console.info('Image is loaded');
      }}
    />
  );
};

StarsRating

The StarsRating component allows to display rating.

Component props:

  • value - current value of the rating
  • min - minimal value of the rating, by default it's 1
  • max - maximum value of the rating, by default it's 5

Example:

const ContentBlock = () => {
  const {
    product,
    settings,
  } = useSelector(state => ({
    product: state.page.product,
    settings: state.settings.rating,
  }), shallowEqual);

  return (
    <Container>
      <Heading as="h2">{product.title}</Heading>
      <LazyImage src={product.image} />
      <Container as="p">{product.description}</Container>
      <StarsRating
        value={product.rating}
        min={settings.min}
        max={settings.max}
      />
    </Container>
  );
};

Spinner

The Spinner component allows to display loading indicator.

Component props:

  • className - CSS class of the spinner
  • ref - reference to the spinner component

Example:

const ContentBlock = () => {
  const { products, loaded } = useSelector(state => ({
    products: state.page.products,
    loaded: state.page.loaded,
  }), shallowEqual);

  return (
    <Container>
      {loaded ? <ProductList items={products} /> : <Spinner className="spinner" />}
    </Container>
  );
};

VideoPlayer

The VideoPlayer component allows to display video player.

Component props:

  • src - path to the video
  • className - CSS class of the video player
  • mute - specifies whether the video should be muted by default
  • hideControls - specifies whether video controls should be hidden
  • autoplay - specifies whether the video should be played automatically
  • loop - specifies whether the video should be looped
  • privacyEnhancedMode - specifies whether the video should be played in privacy enhanced mode
  • cultureName - specifies player language
  • pauseOffScreen - specifies whether video should be paused when exiting the viewport
  • onReady - function which is invoked when the video is loaded
  • onPlay - function which is invoked when the video is played
  • onError - function which is invoked when an error occurs

Example:

const ContentBlock = () => {
  const product = useSelector(state => state.product);

  return (
    <Container>
      <Heading as="h2">{product.title}</Heading>
      <VideoPlayer
        src={product.video}
        className={styles.videoPlayer}
        pauseOffScreen
        privacyEnhancedMode
        cultureName="de"
        onError={error => {
          console.warn(error);
        }}
      />
    </Container>
  );
};
Note

Video player supports YouTube and Vimeo providers only.

ProductPrice

The ProductPrice component allows to display price of the product. It will be rendered based on the price settings in Sana Admin.

Component props:

  • salesPrice - sales price of the product
  • basePrice- base price of the product

Example:

const ContentBlock = () => {
  const product = useSelector(state => state.product);

  return (
    <Container>
      <Heading as="h2">{product.title}</Heading>
      <ProductPrice
        salesPrice={product.salesPrice}
        basePrice={product.basePrice}
      />
    </Container>
  );
};

LowerBoundProductGroupPrice

The LowerBoundProductGroupPrice component allows to display price with discounts of the cheapest product in the product group. It will be rendered based on the price settings in Sana Admin.

Component props:

  • salesPrice - sales price of the cheapest product, which will be displayed as the final price taking discounts into account, if any. The value undefined should be passed to indicate that the price is in the process of loading and the component will display the placeholder. If the value null is passed, the component will display nothing.
  • basePrice- base price of the cheapest product, which does not take discounts into account. This property is optional.

Example:

const ContentBlock = () => {
  const product = useSelector(state => state.product);
  const lowestPriceProduct = product.productGroup.lowestPriceProduct;

  return (
    <Container>
      <LowerBoundProductGroupPrice
        salesPrice={lowestPriceProduct.price}
        basePrice={lowestPriceProduct.listPrice}
      />
    </Container>
  );
};

ProductPricePerBaseUom

The ProductPricePerBaseUom component allows to display product price per one unit of measure.

Component props:

  • baseUomDescription - unit of measure description
  • pricePerBaseUom - price per one unit

Example:

const ContentBlock = () => {
  const product = useSelector(state => state.page.product);

  return (
    <Container>
      <Heading as="h2">{product.title}</Heading>
      <ProductPricePerBaseUom
        pricePerBaseUom={product.price}
        baseUomDescription={product.unitOfMeasure.description}
      />
    </Container>
  );
};

ProductUomBaseQuantity

The ProductUomBaseQuantity component allows to display product quantity.

Component props;

  • uomDescription - unit of measure description
  • uomBaseQuantity - unit of measure quantity to be displayed
  • baseUomDescription - base unit of measure description

Example:

const ContentBlock = () => {
  const product = useSelector(state => state.product);

  return (
    <Container>
      <Heading as="h2">{product.title}</Heading>
      <ProductUomBaseQuantity
        baseUomDescription={product.unitOfMeasure.baseDescription}
        uomBaseQuantity={product.unitOfMeasure.baseQuantity}
        uomDescription={product.unitOfMeasure.description}
      />
    </Container>
  );
};

ProductStock

The ProductStock component allows to display product stock information.

Component props:

  • inventory - amount of available products
  • isOrderable - defines whether the product is orderable
  • stockLevels - allows to specify stock levels
  • forVariant - set to true when the component is used for product variants

stockLevels object:

  • outOfStock - amount at which stock information should be displayed as out of stock
  • lowStock - amount at which stock information should be displayed as low stock
  • maxStockNumber - maximum stock number

Example:

const ContentBlock = () => {
  const product = useSelector(state => state.product);

  return (
    <Container>
      <ProductStock
        inventory={product.inventory}
        stockLevels={{
          lowStock: 20,
          maxStockNumber: 2000,
          outOfStock: 0,
        }}
        isOrderable
      />
    </Container>
  );
};

ConfigurableProductStock

The ConfigurableProductStock component allows to display configurable product stock information.

Component props:

  • inventory - amount of available products

Example:

const ContentBlock = () => {
  const product = useSelector(state => state.product);

  return (
    <Container>
      <ConfigurableProductStock inventory={product.inventory} />
    </Container>
  );
};

UomSelector

The UomSelector allows to display unit of measure selector for product.

Component props:

  • productId - unique identifier of the product which is used to create ID attribute for the selector component
  • blockId - unique identifier of the content block which is used to create ID attribute for the selector component
  • uomId - unique identifier of the current unit of measure
  • uoms - unit of measure objects collection to be displayed as options in the selector
  • onUomChange - function which is invoked on selector change
  • className - CSS class of the selector
  • ariaChangeStatus - allows to specify ARIA status that will be rendered on selector change. It's invisible to the user, but will be announced by screen readers

UOM object:

  • id - unique identifier of the unit of measure
  • description - description of the unit of measure, it will be displayed as the option text in case the Sana text is not found

Example:

const ContentBlock = ({ id }: ContentBlockProps<Model>) => {
  const product = useSelector(state => state.page.product);
  const uoms = product.uoms?.map(uom => ({ id: uom.id, description: uom.description }));
  if (!uoms)
    return null;

  const handleUomChange = (uomId: string) => {
    console.log(uomId);
  };

  return (
    <Container>
      <UomSelector
        className={styles.selector}
        blockId={id}
        productId={product.Id}
        uoms={product.uoms}
        uomId={product.uoms[0].id}
        onUomChange={handleUomChange}
      />
    </Container>
  );
};

QuantityBox

The QuantityBox component allows to input and adjust the quantity value.

Component props:

  • blockId - unique identifier of the content block
  • initialQuantity - initial quantity. If set to DEFAULT, the unit of measure default quantity will be used as initial
  • uom - object that represents unit of measure
  • updateQuantity - function which is invoked to update quantity
  • hideControlsOnBlur - specifies whether controls of the component should be hidden when it's not selected
  • showControlsUnderInputMd - allows to display controls under input on the md screen breakpoint
  • allowEmpty - specifies whether the quantity box can be empty
  • allowResetOnStepDecrease - specifies whether to reset the quantity when decreasing the quantity step below the minimum

UOM object:

  • minimumQuantity - minimum allowed quantity
  • maximumQuantity - maximum allowed quantity
  • defaultQuantity - default quantity value
  • quantityStep - step by which the quantity can be increased or decreased

Example:

const ContentBlock = () => {
  const updateQuantity = (quantity: QuantityModelValue) => {
    console.log(quantity);
  };

  return (
    <Container>
      <QuantityBox
        uom={{
          minimumQuantity: 1,
          maximumQuantity: 10,
        }}
        initialQuantity={1}
        updateQuantity={updateQuantity}
        hideControlsOnBlur
        showControlsUnderInputMd
      />
    </Container>
  );
};

ProductOrderButton

The ProductOrderButton component allows to add product to the basket.

Component props:

  • productId - unique identifier of the product to be added
  • productTitle - title of the product to be added, it's used to construct aria-label attribute of the button, if not specified productId will be used
  • url - URL which leads to the product details
  • to - takes object or parameterless function that returns this object as argument, which is used to navigate to the products details page
  • uom - unit of measure object
  • isOrderable - defines whether the product is orderable, if it's not specified empty placeholder will be rendered, if set to true the text that informs about the product's inaccessibility will be displayed
  • isConfigurable - defines whether the product is configurable
  • hasVariants - defines whether the product has variants
  • quantity - specifies the product quantity
  • disableAddProduct - allows to disable the button

to object:

  • routeName - name of the internal page to which the link will lead
  • params - allows to provide parameters for the link

UOM object:

  • id - unique identifier of the unit of measure
  • quantityStep - interval used to change the quantity value
  • minimumQuantity - minimum allowed quantity
  • maximumQuantity - maximum allowed quantity
  • defaultQuantity - default quantity value

Example:

const ContentBlock = () => {
  return (
    <Container>
      <ProductOrderButton
        productId="ITEM"
        productTitle="Item"
        url="https://sana.doc.example.com"
        to={{
          routeName: 'ProductDetails',
          params: { id: 'ITEM' },
        }}
        isOrderable
      />
    </Container>
  );
};

FullScreenPopup component

The FullScreenPopup allows you to open a full screen modal with content inside of it.

Component props:

  • children - child components that will be rendered inside the modal
  • onClose - function that is called when user pressed "close" button or Escape
  • onKeyDown - function that is called on user input. Receives one argument - key (code of the button, that was pressed, like ArrowLeft)
  • className - attribute to specify CSS class of the container, that renders children

Example:

const ContentBlock = () => {
  const [open, setOpened] = useState(false);
  const [keyPressed, setKeyPressed] = useState('nothing');

  return (
    <>
      <button onClick={() => setOpened(true)}>Open full screen popup</button>
      {open &&
        <FullScreenPopup
          onClose={() => setOpened(false)}
          onKeyDown={e => setKeyPressed(e)}
        >
          You pressed {keyPressed}
        </FullScreenPopup>
      }
    </>
  );
};
Note

The popup will not be shown in the Visual designer.

DateDisplay component

The DateDisplay component allows you to render dates with formatting.

Component props:

  • value - date to render. The input value can be typed as number representing the timestamp (the number of milliseconds since midnight at the beginning of January 1, 1970, UTC), as string representing Date Time String Format or Date object.
  • long-format - boolean parameter that will change the output format from the short variant yyyy-mm-dd to the long variant with a language-sensitive representation of this date in the local timezone.

Example:

import { Container, DateDisplay } from 'sana/elements';

const ContentBlock = () => {
  return (
    <Container>
      <DateDisplay value={new Date("2024-03-14T14:36:00.000Z")} longFormat/>
      <br/>
      <DateDisplay value={new Date("2024-03-14T14:36:00.000Z")} />
    </Container>
  );
};

export default ContentBlock;
Note

Output format can be changed depending on the current locale. For instance short format like yyyy-mm-dd can be changed to dd.mm.yyyy etc.

Tooltip component

The Tooltip component allows you to render the tooltip.

Component props:

  • id - unique identifier of the component
  • body - content that will be rendered in the tooltip popup
  • children - child component to which the tooltip will be added
  • title- title for the tooltip body
  • className - class name for the tooltip
  • bodyClassName - class name for the tooltip body
  • wrapperClassName - class name for the wrapper in which the tooltip and children will be rendered
  • anchorRef - reference that will be passed to the child component, that is, an anchor for the tooltip body
  • sign - specifies if the default sign should be rendered
  • keepOpenedOnScroll - specifies whether the tooltip body will be closed when the page is scrolled
  • opened - specifies if initially tooltip is opened
  • strategy defines the positioning strategy for the tooltip body. The following parameters can be set:
    • absolute - positions the floating element relative to the closest positioned ancestor
    • fixed - positions the floating element relative to the viewport, not affected by scrolling or parent transformations
  • placement - specifies the placement of the tooltip body relative to the children element. Possible values: top, right, bottom, left, top-start, top-end, right-start, right-end, bottom-start, bottom-end, left-start and left-end.
  • options additional tooltip options. The following parameters can be set:
    • scroll$ - subject that is used to provide custom scrolling events
  • setOpened - function that allows to override logic for opening a tooltip body process

Example:

const ContentBlock = () => {
  <Tooltip
    id="id"
    title="Body title"
    body={<p>Body message</p>}
    className="tooltip-custom-classname"
    bodyClassName="tooltip-body-custom-classname"
    wrapperClassName="tooltip-wrapper-custom-class"
    placement="right-start"
  >
    <TextBoxField
      fieldName="name"
      placeholder="text box field"
    />
  </Tooltip>
}

Icons

Icon is a component, that shows configured in themes or default icon.

The list of available icons from ADK:

  • BigArrowLeftIcon
  • BigArrowLeftPassiveIcon
  • BigArrowRightIcon
  • BigArrowRightPassiveIcon
  • MovieIcon
  • ListItemIcon
  • ListSelectedItemIcon
  • SearchIcon
  • SearchButtonIcon
  • TooltipIcon

Icon props:

  • alt - text that will be displayed when the icon is not loaded
  • title - title which is applied to configured icons only, it will be displayed as a tooltip when hovering over the icon

Example:

const ContentBlock = () => <MovieIcon title="movie" alt="movie" className="my-class" />;

Module "webstore/sana/texts"

SimpleText

The SimpleText component allows to show just a pure text.

Component props:

  • textKey - unique key of the text to be displayed. Client application will create a key with the following pattern {addonId}__{textKey} to request text from the server API
  • formatWith - array of React nodes to be inserted into the text, to do it, the text should have indexed placeholders like this Hello, {0}! You have {1} credits left.
  • children- text to be rendered when loading by the text key is failed
  • placeholder - placeholder that is displayed until the text is loaded
  • formatAsHtml - specifies whether the text should be rendered as HTML

Example:

const ContentBlock = () => {
  return (
    <Container>
      <SimpleText
        textKey="Greeting"
        formatWith={[<b>John Doe</b>, 10]}
        placeholder={<span>Loading...</span>}
        formatAsHtml
      />
    </Container>
  );
};

RichText

The RichText allows to render text as HTML.

Component props:

  • textKey - unique key of the text to be displayed. Client application will create a key with the following pattern {addonId}__{textKey} to request text from the server API
  • formatWith - array of React nodes to be inserted into the text, to do it, the text should have indexed placeholders like this Hello, {0}! You have {1} credits left.
  • children- text to be rendered when loading by the text key is failed
  • placeholder - placeholder that is displayed until the text is loaded

Example:

const ContentBlock = () => {
  const fallback = `
    <p>
      <i>Failed to load user data. Try again later or contact administrator.</i>
    </p>
  `;

  return (
    <Container>
      <RichText
        textKey="Greeting"
        formatWith={[<b>John</b>, 10]}
        placeholder={<span>Loading...</span>}
      >
        {fallback}
      </RichText>
    </Container>
  );
};

Module "webstore/sana/forms"

Form

The Form component allows to display a form.

Component props:

  • name - name of the form
  • initialValues - object with initial values of the form
  • className - attribute to specify CSS class of the form
  • children - components that will be rendered inside the form
  • formRef - reference to the form component
  • onSubmit - function to be invoked when the form is submitted
  • onBlur - function to be invoked when the form is out of focus
  • validate - function used to validate form values, it can return FormErrors object or Promise that returns this object, each property of the object consists of the field name as a key and an error message as a value

Example:

import styles from './styles.module.scss';
import type { FormErrors } from 'sana/forms';
import { Button } from 'sana/elements';
import { FieldLabel, Form, FormGroup, TextBoxField } from 'sana/forms';

type FormValues = {
  username: string;
  email: string;
};

type Props = {
  initialValues: FormValues;
};

const ContentBlock = ({ initialValues }: Props) => {
  const validate = (values: FormValues): FormErrors<FormValues> => {
    const isUsernameEmpty = values.username.trim().length === 0;
    const isEmailEmpty = values.email.trim().length === 0;

    const errors: FormErrors<FormValues> = {};

    if (isUsernameEmpty)
      errors['username'] = 'Username cannot be empty.';

    if (isEmailEmpty)
      errors['email'] = 'Email cannot be empty.';

    return errors;
  };

  return (
    <Form
      className={styles.form}
      name="DemoForm"
      onSubmit={() => {}}
      initialValues={initialValues}
      validate={validate}
    >
      <FormGroup
        label={(
          <FieldLabel fieldName="username">
            Username
          </FieldLabel>
        )}
        field={(
          <TextBoxField fieldName="username" />
        )}
      />
      <FormGroup
        label={(
          <FieldLabel fieldName="email">Email</FieldLabel>
        )}
        field={(
          <TextBoxField fieldName="email" />
        )}
      />
      <Button type="submit">Submit</Button>
    </Form>
  );
};
Note

In the example above validate function is used to check if required form inputs were provided, but in real cases validation property can be used for the form fields to achieve the same behavior.

FormGroup

The FormGroup component displays a group of components that are parts of a typical input field control inside a form: an input, a label for this input, validation message and a user-friendly description of the input control.

Note

The FormGroup component must be nested inside a Form component.

Component props:

  • className - an CSS class to apply to the form group
  • label - a React component that will be rendered as label for the input component
  • field - a React component that will be rendered as the input component
  • description - an React node that is rendered as user-friendly description in the form group

Example:

const label = <FieldLabel fieldName="booleanField">My boolean field</FieldLabel>;
const field = (
  <BooleanDropdownField
    fieldName="booleanField"
    fieldTitle="My boolean field"
    required
    validation={{
      required: true,
    }}
  />
);
const description = <span>My user-friendly description for the boolean field.</span>;

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="my-class"
    label={label}
    field={field}
    description={description}
  />
</Form>

CaptchaFormGroup

The CaptchaFormGroup component renders a CAPTCHA in a form in order to prevent robots from automated filling and submitting of forms.

Note

The CaptchaFormGroup component must be nested inside a Form component. It will be rendered only when it is enabled in CAPTCHA settings in Sana Admin.

Component props:

  • fieldName - a unique name for the CAPTCHA field. If there are several CAPTCHAs on the same page they must have different names

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <CaptchaFormGroup
    fieldName="captchaField"
  />
</Form>

RadioFormGroup

The RadioFormGroup component is a container that displays a group of radio button inputs.

Note

The RadioFormGroup component must be nested inside a Form component.

Component props:

  • className - an CSS class to apply to the radio form group
  • field - a React component that will be rendered as the input component

Example:

const field = (
  <BooleanRadioField
    fieldName="booleanRadioField"
    fieldTitle="My field"
    required
    className="field-class"
    validation={{
      required: true,
    }}
  />
);

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="my-class"
    field={field}
  />
</Form>

ReadOnlyFormGroup

The ReadOnlyFormGroup component is the same as the FormGroup with the difference that it is meant to display a field that is read-only and cannot be edited by the user. A simple label will be rendered instead of an input control for the field value.

Note

The ReadOnlyFormGroup component must be nested inside a Form component.

Component props:

  • className - a CSS class to apply to the form group
  • label - a React component that will be rendered as label for the input component
  • field - a React component that will be rendered as the field value component. It must be a read-only component

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <ReadOnlyFormGroup
    label={<label>My Label</label>}
    field={<ReadonlyField fieldName="readOnlyField" />}
  />
</Form>

Checkbox

The Checkbox component allows to display checkbox.

Component props:

  • className - attribute to specify CCS class of the component
  • title - allows to specify tooltip for the component
  • type - type of the checkbox
  • onChange - function to be invoked when value is changed

Example:

<form>
  <Checkbox
    name="demoCheckbox"
    className="demo_checkbox"
    title="Demo Checkbox"
    onChange={value => {}}
  />
</form>

DatePicker

The DatePicker component allows to select date.

Component props:

  • onChange - function to be invoked when the value is changed
  • className - attribute to specify CSS class of the component
  • isValid - specify false when value is not a valid date
  • value - value of the date picker to be displayed, it takes value in format YYYY-MM-DD
  • minDate - minimum allowed date
  • maxDate - maximum allowed date
  • externalLabelId - ID of a label for this component. It's used as ARIA label for assistive screen reader software when the reader announces the input control
  • required - indicates whether value is required to specify
  • calendarRef - reference to the calendar, can be used to access calendar itself
  • id - unique identifier of the component
  • name - name for the input field
  • isDateAvailable - the function which should be used to check date availability.

Example:

const ContentBlock = () => {
  return (
    <form>
      <span id="spanLabelId">Choose your birth date</span>
      <DatePicker
        id="demo_date_picker"
        name="demoDate"
        value={value}
        onChange={() => {}}
        minDate={new Date('2024-01-01')}
        maxDate={new Date('2024-12-31')}
        externalLabelId="spanLabelId"
      />
    </form>
  );
}

export default ContentBlock;

HiddenSubmitButton

The HiddenSubmitButton component is a button invisible for the user that allows to submit a form using the keyboard or assistive technology.

The component has no props.

Example:

<form>
  <input type="text" name="sample">
  <HiddenSubmitButton />
</form>

Input

The Input component allows to display text input field.

Component props:

  • className - CSS class of the input wrapper
  • innerRef - reference to the container element in which the input is wrapped, it can be used to access container element itself
  • inputRef - reference to the input element, it can be used to access input element itself
  • onChange - function to be invoked when the input value changes

Example:

<form>
  <Input
    className="sample"
    onChange={value => setValue(value)}
  />
</form>

Radio

The Radio component allows to display radio input field.

Component props:

  • className - CSS class of the radio wrapper
  • onChange - function to be invoked when the radio value changes
  • children - child components that will be rendered as label of the radio

Example:

const ContentBlock = () => {
  return (
    <form>
      <Radio
        name="demoRadio"
        className="sample"
        onChange={value => {}}
      >
        Sample
      </Radio>
    </form>
  );
};

RadioButtonGroup

The RadioButtonGroup component allows to display radio button group.

Components props:

  • id - unique identifier of the component
  • value - current value of the group
  • items - array of the objects for the group to be displayed
  • onChange - function to be invoked when a button is clicked

Items object:

  • name - name of the item
  • value - value of the item

Example:

const ContentBlock = () => {
  return (
    <Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
      <RadioButtonGroup
        id="demo_group"
        items={[
          { name: 'First', value: 'first' },
          { name: 'Second', value: 'second' },
          { name: 'Third', value: 'third' },
        ]}
        value={value}
        onChange={value => {}}
      />
    </Form>
  );
};

Select

The Select component allows you to render control that contains a menu of options.

Component props:

  • id - unique identifier for select
  • name - name for select
  • items - an array of available items that the component will use to show in the dropdown for the user. Each select item must have value and name properties. value can have the type of boolean, string, number or null
  • value - initial value for component
  • className - attribute to specify CCS class of the component
  • onChange - function to be invoked when value is changed
  • placeholderTextKey - resource text key by which the placeholder value is obtained
  • labeled - identifies the element (or elements) that labels the element it is applied to
  • autoComplete - specifies whether to provide automated assistance in filling out select field values
  • invalid - specifies whether the select is invalid or not
  • shouldReset - enforces component to reset value to default
  • disabled - specifies whether the select disabled or not
  • small - causes a smaller version of a component to be rendered
  • fullWidth - stretch the component to the full width of the container

Example:

<form>
  <Select
    id="select_id"
    items={ [
      { name: "First item", value: 1 },
      { name: "Second item", value: 2 },
    ]}
    value={items[0].value}
    onChange={value => {}}
  />
</form>

TextArea

The TextArea component allows to display multi-line text input field.

Component props:

  • className - CSS class of the textarea wrapper
  • onChange - function to be invoked when the textarea value changes

Example:

<form>
  <TextArea
    name="demoTextArea"
    className="sample"
    onChange={() => {}}
  />
</form>

FieldProps

  • fieldName - name of the field
  • fieldTitle - field title that is displayed in the error message
  • validation - validation parameters for the entered field value. One or more parameters from the ValidationProps can be specified
  • required - specifies the component display behavior, for example if the value is true the empty value will not be displayed in dropdowns

ValidationProps

  • required - specifies whether the field must be filled in. Can be set to true or an object with the following properties:
    • allowWhitespace - specifies whether the input that comprises nothing but white-space characters is considered valid or not
    • validateAgainstFalse - specifies whether the false value is valid
    • message - text that will be displayed if validation fails
  • stringLength - specifies the length limits of the entered value. The following parameters can be set:
    • max - maximum length of the value
    • min - minimum length of the value
    • message - text that will be displayed if validation fails
  • maxLength - specifies the maximum length of the entered value. The following parameters can be set:
    • max - maximum length of the value
    • message - text that will be displayed if validation fails
  • regex - specifies validation using regular expression. The following parameters can be set:
    • pattern - regular expression pattern
    • message - text that will be displayed if validation fails
  • emailAddress - indicates that the entered value must be an email. Can be specified as true or an object with the following fields:
    • message - text that will be displayed if validation fails
  • readableName - indicates that the entered value must be a human-readable name. Can be specified as true or an object with the following fields:
    • message - text that will be displayed if validation fails
  • equalsTo - a strict match with the value. The following parameters can be set:
    • to - comparison value
    • message - text that will be displayed if validation fails
  • notEqualsTo - strict non-compliance with the value. The following parameters can be set:
    • to - comparison value
    • message - text that will be displayed if validation fails
  • range - specifies the range of valid numbers. The following parameters can be set:
    • min - minimum value
    • max - maximum value
    • message - text that will be displayed if validation fails
  • precise - specifies the precision of the number. The following parameters can be set:
    • precision - number precision (the number by which the entered value must be integer divisible)
    • message - text that will be displayed if validation fails
  • datesRange - specifies the valid data range. The following parameters can be set:
    • minDate - minimum date
    • maxDate - maximum date
    • message - text that will be displayed if validation fails
  • minAge - specifies the minimum value of the entered age. The following parameters can be set:
    • minAge - minimum age
    • message - text that will be displayed if validation fails
  • fileAcceptedTypes - specifies the validation by file types. The following parameters can be set:
    • types - list of valid file types as an array of strings
    • message - text that will be displayed if validation fails
  • fileNameMaxLength - specifies the maximum length of the file name. The following parameters can be set:
    • max - maximum length of the file name
    • message - text that will be displayed if validation fails
  • filesMaxSize - specifies the maximum size of files. The following parameters can be set:
    • max - maximum size of files
    • message - text that will be displayed if validation fails
  • custom - the function that specifies custom value validation behavior

ArrayField

The ArrayField component displays and helps perform common array/list manipulations. The value of this field is an array.

Note

The ArrayField component must be nested inside a Form component.

Component props:

  • fieldName - the name of the field
  • children - child component that will be rendered inside the array and has a context object in props with the following fields:
    • push - adds a value to the end of the field's value array
    • remove - removes an element at an index of the field's value array and return it
    • createFieldName - function that returns the name of a field based on its parameters and position in the field's value array

Example:

const SampleForm = () => {
  return (
    <Form name="MyForm" onSubmit={() => { }} initialValues={{ array: [] }}>
      <SampleArray />
    </Form>
  );
};

type ArrayMember = {
  name: string;
};

const arrayFieldName = 'array';
const nameFieldTitle = 'Name';

const SampleArray = () => {
  const { getFieldValue } = useFormContext();
  const list: ArrayMember[] = getFieldValue(arrayFieldName);

  return (
    <ArrayField<ArrayMember> fieldName={arrayFieldName}>
      {({ push, remove, createFieldName }) => (
        <>
          {list.map((_, index) => {
            const nameFieldName = createFieldName(arrayFieldName, index, 'name');

            return (
              <Row key={index}>
                <Col>
                  <FormGroup
                    label={<FieldLabel fieldName={nameFieldName}>{nameFieldTitle}</FieldLabel>}
                    field={(
                      <TextBoxField
                        fieldName={nameFieldName}
                        fieldTitle={nameFieldTitle}
                        required
                        validation={{ required: true }}
                      />
                    )}
                  />
                </Col>
                <Col>
                  <Button type="button" onClick={() => remove(index)}>Remove</Button>
                </Col>
              </Row>
            );
          })}
          <Button type="button" onClick={() => push({ name: '' })}>Add</Button>
        </>
      )}
    </ArrayField>
  );
};

BooleanDropdownField

The BooleanDropdownField component displays a drop-down input control for a boolean field allowing the user to choose between 'Yes' and 'No' values.

Note

The BooleanDropdownField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • labelId - identifier of a label related to this drop-down. When it's present, assistive screen-reading software will be able to read the label's text as the name of the drop-down

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label id="myLabel">My Label</label>}
    field={(
      <BooleanDropdownField
        fieldName="booleanField"
        fieldTitle="My boolean field"
        required
        validation={{
          required: true,
        }}
        labelId="myLabel"
      />
    )}
  />
</Form>

BooleanRadioField

The BooleanRadioField component displays a radio button input control for a boolean field allowing the user to choose between 'Yes' and 'No' values.

Note

The BooleanRadioField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class to apply to the component
  • disabled - HTML attribute that enables or disables the radio input for the user

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label id="myLabel">My Label</label>}
    field={(
      <BooleanRadioField
        fieldName="booleanField"
        fieldTitle="My boolean field"
        required
        validation={{
          required: true,
        }}
        className="fieldClass"
        disabled
      />
    )}
  />
</Form>

CheckboxField

The CheckboxField component displays a checkbox input control.

Note

The CheckboxField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class to apply to the component
  • title - generic HTML title attribute
  • disabled - HTML attribute that enables or disables the checkbox for the user

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <CheckboxField
        fieldName="checkboxField"
        fieldTitle="My checkbox field"
        required
        validation={{
          required: true,
        }}
      />
    )}
  />
</Form>

DateDropdownField

The DateDropdownField component allows the user to enter a date using separate drop-down input controls for day, month and year.

Note

The DateDropdownField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class of the field
  • minDate - minimum allowed date, default value is 1901.01.01
  • maxDate - maximum allowed date, default value is 31.12 of the current year

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label id="myLabel">My Label</label>}
    field={(
      <DateDropdownField
        fieldName="dateField"
        fieldTitle="My date field"
        required
        validation={{
          required: true,
        }}
        className="fieldClass"
        minDate={new Date(2000, 0, 1)}
        maxDate={new Date(2024, 11, 31)}
      />
    )}
  />
</Form>

DatePickerField

The DatePickerField component allows the user to select a date from the calendar in a drop-down control

Note

The DatePickerField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class to apply to the component
  • minDate - minimum allowed date, default value is 1901.01.01
  • maxDate - maximum allowed date, default value is 2100.11.31
  • externalLabelId - identifier of a label related to this component. When it's present, assistive screen-reading software will be able to read the label's text as the name of the date picker
  • isDateAvailable - the function which should be used to check date availability.

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <DatePickerField
        fieldName="datePickerField"
        fieldTitle="My date picker field"
        required
        validation={{
          required: true,
        }}
        className="fieldClass"
        minDate={new Date('2024-01-01')}
        maxDate={new Date('2024-12-31')}
        externalLabelId="externalLabel"
      />
    )}
  />
</Form>

DecimalField

The DecimalField component displays a numeric input control which allows only decimal values.

Note

The DecimalField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • asCurrency - flag, should be enabled when used for currency values, e.g. prices. When set then the value will be formatted according to current currency format
  • className - CSS class to apply to the component
  • disabled - HTML attribute that enables or disables the input for the user
  • placeholder - text that is shown inside the input control when there is no value yet
  • maxLength - number that specifies how many digits are allowed to be typed in the input control

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <DecimalField
        fieldName="decimalField"
        fieldTitle="My decimal field"
        required
        validation={{
          required: true,
        }}
        asCurrency
        disabled={false}
        placeholder="Type in some number"
        maxLength={15}
      />
    )}
  />
</Form>

The DropdownField component displays a drop-down input control.

Note

The DropdownField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • items - a list of items that will be rendered as drop-down options. Each item has a name property of type string and a value property, which can be one of the possible types string, number, boolean The value property also supports null
  • labelId - identifier of a label related to this drop-down. When it's present, assistive screen-reading software will be able to read the label's text as the name of the drop-down

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <DropdownField
        fieldName="dropdownField"
        fieldTitle="My drop-down field"
        required
        validation={{
          required: true,
        }}
        items={[
          { name: 'empty', value: null },
          { name: 'option 1', value: 'option1' },
          { name: 'option 2', value: 'option2' },
        ]}
        labelId="myLabel"
      />
    )}
  />
</Form>

IntegerField

The IntegerField component displays a numeric input control which allows only integer values.

Note

The IntegerField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class to apply to the component
  • disabled - HTML attribute that enables or disables the input for the user
  • placeholder - text that is shown inside the input control when there is no value yet
  • maxLength - number that specifies how many digits are allowed to be typed in the input control

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <IntegerField
        fieldName="decimalField"
        fieldTitle="My decimal field"
        required
        validation={{
          required: true,
        }}
        asCurrency
        disabled={false}
        placeholder="Type in some number"
        maxLength={15}
      />
    )}
  />
</Form>

RadioField

The RadioField component displays a radio button input control for a field allowing the user to choose one of multiple values.

Note

The RadioField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class of the field
  • items - list of items that will be rendered as radio buttons. Each item has name property of type ReactNode and value property than can be any value
  • disabled - HTML attribute that enables or disables the input for the user

Example:

import { FormGroup, RadioField, Form } from 'sana/forms';

const ContentBlock = () => {
  const items = [
    { name: "Radio option 1", value: 1},
    { name: <label id="radioOption2">Radio option 2</label>, value: {}},
  ];

  return (
    <Form name="MyForm" onSubmit={() => {}} >
      <FormGroup
        className="class"
        label={<label id="myLabel">My Label</label>}
        field={(
          <RadioField
            fieldName='radioFieldName'
            fieldTitle="My radio field"
            required
            validation={{
              required: true,
            }}
            className="radioFieldClass"
            items={items}
          />
        )}
      />
    </Form>
  );
}

ReadonlyDateField

The ReadonlyDateField component displays the value of the date as a read-only text without any input control.

Note

The ReadonlyDateField component must be nested inside a Form component. Also this component is meant to be used within the ReadOnlyFormGroup component.

Component props:

  • fieldName - the name of the field

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{ readonlyDateField: "2024-05-09T00:00:00Z" }}>
  <ReadOnlyFormGroup
    label={<ReadonlyFieldLabel fieldName="readonlyDateField">Readonly date field title</ReadonlyFieldLabel>}
    field={<ReadonlyDateField fieldName="readonlyDateField" />}
  />
</Form>

ReadonlyField

The ReadonlyField component displays the value of the field as a read-only text without any input control.

Note

The ReadonlyField component must be nested inside a Form component. Also this component is meant to be used within the ReadOnlyFormGroup component.

Component props:

  • fieldName - the name of the field

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <ReadOnlyFormGroup
    label={<label>My Label</label>}
    field={<ReadonlyField fieldName="readOnlyField" />}
  />
</Form>

TextAreaField

The TextAreaField component displays a text area input control.

Note

The TextAreaField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class to apply to the component
  • disabled - HTML attribute that enables or disables the input for the user
  • placeholder - text that is shown inside the input control when there is no value yet
  • maxLength - number that specifies how many characters are allowed to be typed in the input control

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <TextAreaField
        fieldName="textAreaField"
        fieldTitle="My text area field"
        required
        validation={{
          required: true,
        }}
        disabled={false}
        placeholder="Type in some text"
        maxLength={150}
      />
    )}
  />
</Form>

TextBoxField

The TextBoxField component displays a text box input control.

Note

The TextBoxField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • type - HTML input type attribute. If not specified then the input will be rendered with type="text" by default
  • className - CSS class to apply to the component
  • disabled - HTML attribute that enables or disables the input for the user
  • placeholder - text that is shown inside the input control when there is no value yet
  • maxLength - number that specifies how many characters are allowed to be typed in the input control

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <TextBoxField
        type="password"
        fieldName="textAreaField"
        fieldTitle="My text area field"
        required
        validation={{
          required: true,
        }}
        disabled={false}
        placeholder="Type in some text"
        maxLength={150}
      />
    )}
  />
</Form>

FileField

The FileField component displays a file input control.

Note

The FileField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • className - CSS class to apply to the component
  • disabled - HTML attribute that enables or disables the input for the user
  • multiple - HTML attribute that allows the user to select more than one file
  • handleChange - function to be invoked when the input value changes

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <FileField
        fieldName="fileField"
        fieldTitle="My file field"
        required
        validation={{
          required: true,
        }}
        className="fieldClass"
        disabled={false}
        multiple={true}
        handleChange={() => {}}
      />
    )}
  />
</Form>

CustomField

The CustomField component displays a custom input control.

Note

The CustomField component must be nested inside a Form component. Also this component is meant to be used within a form group component, for example a FormGroup.

Component props:

  • All FieldProps
  • children - child component that will be rendered and has a field object in props with the following fields:
    • name - name of the field
    • value - value of the field
    • touched - flag which specifies whether field has been touched/visited
    • errors - list of validation errors
    • onChange - function to be invoked when input value is changed
    • onBlur - function to be invoked when input has lost focus

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<label>My Label</label>}
    field={(
      <CustomField
        fieldName="customField"
        fieldTitle="My custom field"
        required
        validation={{ required: true }}
      >
        {({ name, value, onChange, onBlur }) => (
          <input
            name={name}
            value={value || ''}
            onChange={e => onChange(e.target.value)}
            onBlur={onBlur}
          />
        )}
      </CustomField>
    )}
  />
</Form>

FieldError

The FieldError is a component that displays an error message for a given field.

Component props:

  • className - a CSS class to apply to the label
  • fieldName - the name of the field for which errors are monitored

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    className="class"
    label={<FieldLabel fieldName="textBoxField">Textbox field input</FieldLabel>}
    field={<TextBoxField fieldName="textBoxField" fieldTitle="My text box field"/>}
  />
  <FieldError fieldName="textAreaField" />
</Form>

FieldLabel

The FieldLabel component displays the label for the form field.

Component props:

  • fieldName - the name of the field
  • children - child components that will be rendered inside the label
  • className - a CSS class to apply to the label
  • focusToFieldOnClick - allows specify that the target field should be focused upon clicking on it's corresponding label
  • required - the attribute appends a special character to the end of the label message to indicate that the target field is required.

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormGroup
    label={<FieldLabel fieldName="formField">My Label</FieldLabel>}
    field={<TextBoxField fieldName="formField" />}
  />
</Form>

FormError

The FormError is a component that displays an error message about the form in which it is placed and there is an error message present.

Component props:

  • className - a CSS class to apply to the label

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <FormError className='customClassName' />
</Form>

ReadonlyFieldLabel

The ReadonlyFieldLabel component displays the label for the read-only field.

Component props:

  • fieldName - the name of the field
  • children - child components that will be rendered inside the label
  • className - a CSS class to apply to the label

Example:

<Form name="MyForm" onSubmit={() => {}} initialValues={{}}>
  <ReadOnlyFormGroup
    label={<ReadonlyFieldLabel fieldName="readonlyField">My Label</ReadonlyFieldLabel>}
    field={<ReadonlyField fieldName="readonlyField" />}
  />
</Form>

ProductCustomerSpecificId

The ProductCustomerSpecificId component displays the customer specific product ID (customer specific item number).

Component props:

  • customerSpecificId - the customer specific product identifier or JSX component which holds the identifier
  • placeholder - the JSX component which will be shown while required for rendering additional data is being loaded

Example:

  <ProductCustomerSpecificId customerSpecificId={value} placeholder={placeholder} />