# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: UIGradient
type: class
memory_category: Instances
summary: |
  Applies a color and transparency gradient to the parent `Class.GuiObject`.
description: |
  `UIGradient` applies a color and transparency gradient to the parent
  `Class.GuiObject`. The appearance of the gradient is configurable through its
  `Class.UIGradient.Color|Color`, `Class.UIGradient.Transparency|Transparency`,
  `Class.UIGradient.Offset|Offset`, `Class.UIGradient.Rotation|Rotation`,
  `Class.UIGradient.Scale|Scale`, `Class.UIGradient.TileMode|TileMode`, and
  `Class.UIGradient.Type|Type`.

  `UIGradient` will not apply to child or descendant
  `Class.GuiObject|GuiObjects`. In order to apply the same gradient to multiple
  objects, you will need multiple gradient instances.

  See also [appearance modifiers](../../../ui/appearance-modifiers.md#gradient)
  for more information on the `UIGradient` modifier and how it works.

  #### Supported Objects

  You can apply `UIGradient` modifiers to `Class.Frame`, `Class.TextLabel`,
  `Class.TextButton`, `Class.ImageLabel`, `Class.ImageButton`, `Class.Path2D`,
  and `Class.ViewportFrame`. However, `Class.ScrollingFrame` and `Class.TextBox`
  are not currently supported.

  #### Performance Considerations

  In order to efficiently use a `UIGradient`, follow these principles:

  - Avoid using more than 6 color stops on the `Class.UIGradient.Color|Color`
    sequence.

  - Avoid using a `UIGradient` on any object that applies a text stroke
    (`Class.TextLabel.TextStrokeColor3|TextStrokeColor3`), as the gradient will
    try to blend with strokes and borders, and may cause performance issues.

  - Avoid setting `Class.UIGradient.Color|Color` and
    `Class.UIGradient.Transparency|Transparency` frequently: this causes the
    sequence of colors to rebuild often, which is expensive. If possible, set
    these properties only once and try to animate the
    `Class.UIGradient.Offset|Offset` or `Class.UIGradient.Rotation|Rotation`
    properties to achieve a similar effect. Alternatively, you can change the
    color of the parent `Class.GuiObject` using such properties as
    `Class.GuiObject.BackgroundColor3|BackgroundColor3`,
    `Class.ImageLabel.ImageColor3|ImageColor3`, or
    `Class.TextLabel.TextColor3|TextColor3`.

  - When applying an unchanging gradient on a UI element whose state changes a
    lot, there is a tradeoff between using a `UIGradient` (processing time) and
    a static gradient image (memory).
code_samples: []
inherits:
  - UIComponent
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: UIGradient.Color
    summary: |
      Determines the color blended with the parent `Class.GuiObject` along the
      length of the gradient.
    description: |
      This property describes the color to blend with the parent
      `Class.GuiObject` along the provided `Datatype.ColorSequence`. This
      property works in a similar manner to `Class.Beam.Color` or
      `Class.Trail.Color`, except that it applies over a distance determined by
      the `Class.UIGradient.Offset|Offset` and
      `Class.UIGradient.Rotation|Rotation`.
    code_samples: []
    type: ColorSequence
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: UIGradient.Enabled
    summary: |
      Whether the gradient is enabled or not.
    description: |
      Whether the gradient is enabled or not.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: UIGradient.Offset
    summary: |
      Determines the scalar translation of the gradient from the center of the
      parent `Class.GuiObject`.
    description: |
      This property determines the scalar translation of the gradient from the
      center of the parent `Class.GuiObject`. It is a scalar translation,
      meaning that the actual pixel offset is determined by the
      `Class.GuiBase2d.AbsoluteSize|AbsoluteSize` of the parent
      `Class.GuiObject`. For example, a value of `(1, 0)` shifts the gradient
      horizontally to the right by a distance equal to the parent object's size.
      Depending on the `Class.UIGradient.Rotation|Rotation`, this may cause the
      gradient to be partially visible or not visible at all.

      Also see `Class.UIGradient.Rotation|Rotation` which also affects the
      geometry of the applied gradient.
    code_samples: []
    type: Vector2
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: UIGradient.Rotation
    summary: |
      Determines the clockwise rotation in degrees of the gradient starting from
      left to right.
    description: |
      This property determines the **clockwise** rotation in degrees of the
      `UIGradient` starting from left to right. The beginning and end control
      points snap to the edges of the parent `Class.GuiObject`, but maintain the
      provided rotation.

      Also see `Class.UIGradient.Offset|Offset` which also affects the geometry
      of the applied gradient.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: UIGradient.Scale
    summary: |
      Multiplies the extent of the gradient, controlling how much of the
      color/transparency sequence is visible within the element.
    description: |
      This property multiplies the extent of the gradient, controlling how much
      of the color/transparency sequence is visible within the parent
      `Class.GuiObject`.

      - A value of `1` (default) means the full sequence spans the element
        exactly once.

      - Values **less** than `1` compress the gradient so that the full sequence
        fits in a smaller region. The remaining area is determined by
        `Class.UIGradient.TileMode|TileMode`. Note that `Scale` is clamped to a
        minimum of `0.001` to avoid degenerate gradients.

      - Values **greater** than `1` stretch the gradient beyond the element
        bounds so that only a portion of the sequence is visible.

      The effect of `Scale` also depends on the gradient's
      `Class.UIGradient.Type|Type`:

      - `Enum.GradientType.Linear` — `Scale` affects the distance between the
        start and end control points.

      - `Enum.GradientType.Radial` — `Scale` affects the radius of the radial
        gradient.

      - `Enum.GradientType.Elliptical` — `Scale` affects both radii of the
        elliptical gradient.

      - `Enum.GradientType.Conical` — `Scale` affects the angular sweep, clamped
        so that the sweep does not exceed a full revolution.

      See also `Class.UIGradient.TileMode|TileMode` which determines how the
      gradient repeats when `Scale` causes it to not fill the entire element.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: UIGradient.TileMode
    summary: |
      Determines how the gradient repeats.
    description: |
      This property determines what happens when the gradient
      `Class.UIGradient.Scale|Scale` is less than `1` or when
      `Class.UIGradient.Offset|Offset` shifts the gradient so that it does not
      fully cover the element. See `Enum.GradientTileMode` for possible values
      and their effect.

      See also `Class.UIGradient.Scale|Scale` which controls how much of the
      color/transparency sequence is visible.
    code_samples: []
    type: GradientTileMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: UIGradient.Transparency
    summary: |
      Determines how much the parent `Class.GuiObject` can be seen through along
      the length of the gradient.
    description: |
      This property describes how opaque the parent UI element will be along the
      provided `Datatype.NumberSequence`. This property works in a similar
      manner to `Class.Beam.Transparency` or `Class.Trail.Transparency`, except
      that it applies over a distance determined by the
      `Class.UIGradient.Offset|Offset` and `Class.UIGradient.Rotation|Rotation`.

      Note that the envelope values of the
      `Datatype.NumberSequenceKeypoint|NumberSequenceKeypoints` are ignored.
    code_samples: []
    type: NumberSequence
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: UIGradient.Type
    summary: |
      Determines the shape of the gradient as linear, radial, elliptical, or
      conical.
    description: |
      This property determines how the gradient varies across the parent
      `Class.GuiObject`. See `Enum.GradientType` for possible values and their
      effect.

      See also `Class.UIGradient.Scale|Scale` which controls how much of the
      color/transparency sequence is visible, and
      `Class.UIGradient.TileMode|TileMode` which determines repetition behavior.
    code_samples: []
    type: GradientType
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
methods: []
events: []
callbacks: []