DOCSEARCHbyAlgolia
Submit Docs

Freshworks Crayons Design System

repository·next·Indexed 42 days ago

https://github.com/freshworks-oss/crayons

A design system implementation using Web Components built with StencilJS to provide a consistent UI library for Freshworks applications. Version 4.0.0 includes a core component library, icon library, and i18n library, featuring tree-shakable, lazy-loaded components that work in vanilla HTML/JavaScript or via official React bindings.

Tokens
188.2K
Snippets
478
Records
657
Agent score
52%

What's inside Crayons

  1. Overview of @freshworks/crayons-i18n

    next

    The @freshworks/crayons-i18n library is an internationalization (i18n) framework designed specifically for use with crayons components. It enables applications to handle multi-language support by providing several core capabilities:

    • User language detection: Automatically identifying the user's preferred language.
    • Proper pluralizations: Handling different grammatical rules for plural forms.
    • Translation context: Providing context for translations to ensure accuracy.
    • Nesting of keys: Allowing organized, hierarchical translation structures.
    • Interpolation: Supporting variable replacement within translated strings.

  2. Overview of @freshworks/crayons-custom-objects

    next

    The @freshworks/crayons-custom-objects package provides an extension of Crayons components. It is a collection of Web Components designed to help developers build applications that adhere to the Freshworks Design System UX standards.

    These components are versatile and can be used in:

    • Traditional frontend view libraries/frameworks (e.g., React, Vue, Angular).
    • Standard JavaScript in the browser without a framework.

    A key feature included in this package is support for Custom Objects / Conversation Properties.

  4. Overview of Crayons features

    next

    Crayons is a library of UI components built with Stencil designed to help create uniform user interfaces adhering to the Freshworks Design System.

    Key features include:

    • Optimized: Tiny, tree-shakable, and lazy-loaded components.
    • Zero Config: No build or compiling required; simply add static files.
    • Customizable: Style components using CSS Variables.
    • Flexible: Works in vanilla HTML/JavaScript or via framework bindings like React.

  6. Configure form fields using formSchema

    next

    The fw-form component is driven by a formSchema object. Each field in the fields array defines the behavior and appearance of a form element.

    Key Field Properties:

    • id: Unique identifier for the field.
    • name: The key used in the resulting values object upon submission.
    • label: The text displayed to the user.
    • type: The type of input (e.g., TEXT, EMAIL, DATE, MULTI_SELECT, DROPDOWN, RADIO, CHECKBOX, NUMBER, PARAGRAPH, DECIMAL).
    • required: Boolean indicating if the field must be filled.
    • choices: An array of options for selection-based types. For DROPDOWN and MULTI_SELECT, ensure choices are mapped to include text and value properties to match Crayons component requirements.
    • position: Determines the order of the field.
    • placeholder: Hint text shown in the input.
    • hint: Descriptive text displayed below the field.
    const formSchema = {
  name: 'Test Form',
  fields: [
    {
      id: 'unique-id',
      name: 'first_name',
      label: 'First Name',
      type: 'TEXT',
      required: true,
      placeholder: 'Enter…',
      hint: 'Please provide a text'
    },
    {
      id: 'choice-id',
      name: 'gender',
      label: 'Gender',
      type: 'RADIO',
      choices: [
        { id: 1, value: 'Female' },
        { id: 2, value: 'Male' }
      ]
    }
  ]
};

// Apply to form
formElement.formSchema = formSchema;

  8. Use FORMSERV mapperType for custom schemas

    next

    By default, fw-form uses the LEGO schema. To use a FORMSERV schema instead, set the mapperType property to 'FORMSERV'. This allows the form to support FORMSERV specific field types and structures out of the box.

    When using FORMSERV, you may need to map your schema fields to match the expected properties of Crayons components. For example, if a field type is a selection type (e.g., type 2 or 18), you might need to map value to text and id to value within the choices array to ensure compatibility.

    // Create the form element
var formFs = document.createElement('fw-form');

// Set mapperType to 'FORMSERV' to support FORMSERV schema types
formFs.mapperType = 'FORMSERV';

// Example of mapping schema choices for compatibility
var fieldsFs = formServSchema.fields.map((field) => {
  if (field.type === 2 || field.type === 18) {
    return {
      ...field,
      choices: field.choices?.map((f) => ({
        ...f,
        text: f.value,
        value: f.id,
      })),
    };
  }
  return field;
});

// Apply the processed schema
formFs.formSchema = { ...formServSchema, fields: fieldsFs };

  12. Understand fw-datepicker prop precedence

    next

    When configuring date constraints, fw-datepicker follows a specific precedence order to resolve contradictions between max-date, min-date, max-year, and min-year.

    Precedence Order: max-date > min-date > max-year > min-year

    Behavioral Rules:

    • If max-date and min-date contradict, min-date is ignored. max-year is automatically set based on max-date, and min-year resets to the default 1970.
    • If max-year and min-year contradict, min-year is ignored and reset to the default 1970.
    • If max-year and max-date contradict, max-year is ignored and recalculated based on max-date.
    • If min-year and min-date contradict, min-year is ignored and recalculated based on min-date.